{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"1c3ec4a1-db46-4e18-ae00-f0efd8bb73fd","name":"BIMS OAuth API","description":"# Overview\n\nThe BIMS Authorization gateway greatly simplifies and allows for a single sign on interface across most Tetfund powered applications and users. Essentially, this helps to enable users access various services and resources using their Tetfund managed Identity.\n\nOAuth 2.0 is the industry-standard authorization protocol that allows applications to obtain requested access to user accounts over the HTTP service with the user’s approval.\n\nBy creating an **OAuth app (or Client)** on the [BIMS Portal](https://bims.tetfund.gov.ng/get-started), you can securely integrate with the **BIMS** APIs and access users' authorized data using a user-based authentication approach.\n\n## Before you begin\n\nTo use this guide, you need:\n\n- **A registered API app.** This is what's interacting with the API and requesting authentication. Haven't registered yet? [Get started here](https://bims.tetfund.gov.ng/get-started).\n    \n\n**NOTE:** You might also consider using our official libraries for PHP, Python, Node.js, and other programming languages. The libraries help to simplify complicated coding by handling all the HTTP requests on your behalf. For more information, see our [Libraries and SDKs](#) page.\n\n## Understanding the authentication process\n\nThe **BIMS** API uses the open [OAuth 2.0](https://oauth.net/) standard for all your app-authentication needs. Under the OAuth 2.0 framework, a third party — that's you — asks a resource owner — that's your app's end user — for permission to access their **BIMS** data.\n\nIf the resource owner grants this permission, we issue you an _access token_. This is a special string of characters that works like a password. You present the access token with your API requests whenever you're asking for protected information.\n\nWhat we've just described is an _authenticated_ access token, because it's tied to a particular user who has an Identity of **BIMS**.\n\nAn access token has one or more scopes, or general domains. The scopes determine the types of access that token does and doesn't permit. During the authentication process, you can specify exactly which scopes your app needs based on the list in the table below. If you try to make an API request with an access token that doesn't have the right scope, the API will deny the request.\n\n## Understanding authentication workflows\n\nOAuth 2.0 supports a number of different methods or _workflows_ for authentication based on the _grant type_, or the way in which authentication is granted.\n\nFor the purposes of the **BIMS** API, the only supported grant type for now is **authorization code**.\n\n# Obtaining an Access Token\n\nSo to summarize what we've covered so far: if you want to make API requests, you need to have an access token. And if you want to get an access token, you need to follow the authentication workflow.\n\n## Using the authorization code grant\n\nWith the _authorization code_ grant, the end user explicitly consents for your app to access their profile data, including exactly which scopes to permit or deny. The front end and logic of the consent mechanism are all on our side; you send your end user to us through a browser, and we take care of it. You don't even need to log them in. We send them back to you with an authorization code, which you present to the API in exchange for an access token. This access token resides on the server, and it remains active as long as we perceive that you're using it.\n\nHere are the general steps:\n\n- **Step 1.** Send your end user to the authorization URL.\n    \n- **Step 2.** Receive access permission from your end user.\n    \n- **Step 3.** Get the authorization code.\n    \n- **Step 4.** Send us the authorization code.\n    \n- **Step 5.** Get the access token.\n    \n\n## 1\n\nDirect your end user to the following address:\n\n```\nhttps://bims.tetfund.gov.ng/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}&scope={scope_list}\n\n ```\n\nSee the table below for details about the query parameters.\n\n| Query parameter | Description |\n| --- | --- |\n| `response_type` | The OAuth response type. Use `code` for the authorization code grant. |\n| `client_id` | The client identifier of your app. To get this value, access your app's information page from [your dashboard](https://bims.tetfund.gov.ng/login). |\n| `redirect_uri` | A redirect URI associated with your app. To add or review redirect URIs, access your app's information page from [your dashboard](https://bims.tetfund.gov.ng/login). |\n| `state` | An arbitrary value. We return this value to you later as a security measure. |\n| `scope` | The space-separated list of scopes that you want to be able to access. This field is optional, and its default value is `public private`. |\n\nIt doesn't matter how you get your end user to the authorization URL. One of the most common ways is to include the link on a web page. Just make sure that you use the correct parameter values for `response_type`, `redirect_uri`, `scope`, and so on. If you don't, the request fails, and you may get a 404 page.\n\n## 2\n\nAs soon as your end user arrives, we enable them to log into their existing account (assuming that they aren't already logged in), and then we ask them to accept or deny your app's request to access their private information. They can also choose which access scopes to permit if you asked for any scope other than the default `profile` scope.\n\n## 3\n\nOnce they accept, we send them to the redirect URI, along with the code and state query parameters, for example;\n\n```\nhttps://your-app.com/redirect-url?code={code}&state={state}\n\n ```\n\nSee the table below for more information.\n\n| Query parameter | Description |\n| --- | --- |\n| `code` | The authorization code to exchange for an access token. |\n| `state` | The value that you specified for the `state` query parameter in the authorization URL. If this value doesn't match the original, don't attempt to exchange the code for a token. |\n\n**NOTE:** We retain any custom query parameters that you include with your URI.\n\n## 4\n\nYou now have the authorization code that you can exchange for an access token, so make a POST request to `/oauth/token`:\n\n```\nPOST https://bims.tetfund.gov.ng/oauth/token\n\n ```\n\nThe headers to send appear in the table below.\n\n| Header | Set value to |\n| --- | --- |\n| `Content-Type` | `application/json` |\n| `Accept` | `application/json` |\n\nIn the request body, send the `grant_type` field with the value `authorization_code`. You must also set `code` to the authorization code string that you just received and `redirect_uri` to the redirect URI that you specified previously — don't use a different redirect URI.\n\nYou can get your app's client identifier and client secret from your dashboard, which you will also add to the request body.\n\n``` json\n{\n  \"grant_type\": \"authorization_code\",  \n  \"client_id\": \"{client-id}\",\n  \"client_secret\": \"{client-secret}\",\n  \"code\": \"{code}\",\n  \"redirect_uri\": \"{redirect_uri}\"\n}\n\n ```\n\nSee the table below for descriptions of common errors.\n\n| HTTP code | Error code | Description |\n| --- | --- | --- |\n| 400 | `invalid_token` | Your code isn't valid, or the callback and the redirect URI don't match. |\n| 400 | `unsupported_grant_type` | The value of the `grant_type` field isn't `authorization_code`. |\n\n## 5\n\nThe API responds with the access token and details about the authenticated user (see the section below).\n\n``` json\n{\n  \"access_token\": \"{token}\",\n  \"token_type\": \"bearer\",\n  \"refresh_token\": \"{refresh-token}\",\n  \"expires_in\": 58960,\n  \"scope\": \"{scope-list}\",\n  \"user\": {\n      \"id\": 6212,\n      \"bims_id\": \"BIMS23101STD27069\"\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"johndoe3@gmail.com\",\n      \"phone\": \"07011227815\",\n      \"type\": \"student\",\n      \"unique_id\": null,\n      \"is_verified\": true,\n      \"photo\": \"https://res.cloudinary.com/myskoolp/image/upload/c_fill,g_face,h_220,w_220/v1/bims/users/defaults/male.jpg\",\n      \"institution\": 69,\n      \"institution\": {\n        \"id\": 69,\n        \"short_name\": \"FCEYOLA\",\n        \"name\": \"Federal College Of Education Yola\"\n      },\n      \"institution_admin\": false,\n  }\n}\n\n ```\n\n| Field | Description |\n| --- | --- |\n| `access_token` | The access token string. |\n| `token_type` | The type of the access token. For the BIMS API, the value of this field is always `bearer`. |\n| `refresh_token` | A token that you can use to get a new access token without the user's interaction. |\n| `scope` | The space-separated list of scopes that your app has permission to access. |\n| `user` | The complete representation of the authenticated end user. |\n\n**NOTE:** There are 5 user types that can be returned. A list and brief description will be given for each below:\n\n1. **admin:** This user type refers to the BIMS application admin who is authorised to provide support to institution users and client users in resolving issues and managing the application. This user data typically comes without Institution ID, i.e \\*institution_id = null\\*\n    \n2. **student:** This user type refers to a student of an institution and the user data returned includes an Institution ID and data.\n    \n3. **lecturer:** This user type refers to an Academic staff of an institution and the user data returned includes an Institution ID and data.\n    \n4. **staff:** This user type refers to a Non-Academic staff of an institution and the user data returned includes an Institution ID and data.\n    \n5. **client:** This user type refers to client application admins. For instance, TERAS is a client application on BIMS and the user who manages this account is of the client user type. This user typically doesn’t come with an Institution ID, i.e \\*institution_id = null\\*. Note: It is recommended that you shouldn’t authenticate this user type on your application except your application’s admin. This is because, there are other client applications on BIMS and you might not want them to access your application. You may authenticate them if this is not the case.\n    \n\n# Get User By Token\n\nAdditionaly, you can also get the user by the access token generated from number 5 above.\n\n```\nPOST https://bims.tetfund.gov.ng/oauth/userinfo\n\n ```\n\nThe headers to send appear in the table below:\n\n| Header | Set value to |\n| --- | --- |\n| `Content-Type` | `application/json` |\n| `Accept` | `application/json` |\n| Authorization | Bearer `access_token` |\n\nThe API then responds by getting the user authenticated from the access token. See the response structure below:\n\n``` json\n{\n      \"id\": 6212,\n      \"bims_id\": \"BIMS23101STD27069\"\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"johndoe3@gmail.com\",\n      \"phone\": \"07011227815\",\n      \"type\": \"student\",\n      \"unique_id\": null,\n      \"is_verified\": true,\n      \"photo\": \"https://res.cloudinary.com/myskoolp/image/upload/c_fill,g_face,h_220,w_220/v1/bims/users/defaults/male.jpg\",\n      \"institution\": 69,\n      \"institution\": {\n        \"id\": 69,\n        \"short_name\": \"FCEYOLA\",\n        \"name\": \"Federal College Of Education Yola\"\n      },\n      \"institution_admin\": false,\n}\n\n ```\n\n# Logout User for Client\n\n```\nhttps://account.bims.ng/clients/BIMS-23-Q2EXXN/users/BIMS23AD50234/logout?redirect_to={my_redirect_url}\n\n ```\n\nThe purpose of this endpoint is to log out the active session of the user on the bims account application. This also revokes the token of the user on the device. To perform this request:\n\n1. REDIRECT your user to the above url from within your application.\n    \n2. The query param `redirect_to` must be present in ther request url and should be a valid url for where you want the user redirected to after they've been logged out, e.g: your application's login url.\n    \n\n**NOTE:** _The host for this particular request is different from the other requests in this documentation, i.e_ [<code>https://account.bims.ng</code>](https://account.bims.ng)\n\n| **Query Param** | **Description (example)** |\n| --- | --- |\n| `redirect_to` | Your app's login url or home page to redirect your user after logout.  <br>e.g: `https://exampleapp.com/login` |\n\n# The BIMS Badge\n\nTypically, when implementing the BIMS OAuth flow, you'd usually have a button that serves as a starting point to take your users to the BIMS OAuth server to authorize your app. This button would usually read \\*\"Continue with BIMS\"\\* or something similar.  \nYou may want to add the BIMS logo to this button for a better visual experience.  \nYou may [Download the BIMS logo here](https://bims.tetfund.gov.ng/img/logo.png).","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"7518841","collectionId":"1c3ec4a1-db46-4e18-ae00-f0efd8bb73fd","publishedId":"UzQxLPME","public":true,"publicUrl":"https://documenter-api.postman.tech/view/7518841/UzQxLPME","privateUrl":"https://go.postman.co/documentation/7518841-1c3ec4a1-db46-4e18-ae00-f0efd8bb73fd","customColor":{"top-bar":"005428","right-sidebar":"005428","highlight":"058710"},"documentationLayout":"classic-single-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":"BIMS OAUTH Docs"}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/607d88c9-ad4a-42f7-8e4a-dc78f96d1841/bG9nby5wbmc=","colors":{"top-bar":"005428","right-sidebar":"005428","highlight":"058710"}},{"name":"light","logo":"https://content.pstmn.io/607d88c9-ad4a-42f7-8e4a-dc78f96d1841/bG9nby5wbmc=","colors":{"top-bar":"005428","right-sidebar":"005428","highlight":"058710"}}]}},"version":"8.10.1","publishDate":"2024-03-20T21:02:41.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"BIMS OAUTH Docs","description":""},"logos":{"logoLight":"https://content.pstmn.io/607d88c9-ad4a-42f7-8e4a-dc78f96d1841/bG9nby5wbmc=","logoDark":"https://content.pstmn.io/607d88c9-ad4a-42f7-8e4a-dc78f96d1841/bG9nby5wbmc="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/6bf5d6fc195cd2da4a01d172e08a1341bc6cf1886d12972ec01cfdb0ec8a1144","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/UzQxLPME"}