The 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.
\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.
\nBy creating an OAuth app (or Client) on the BIMS Portal, you can securely integrate with the BIMS APIs and access users' authorized data using a user-based authentication approach.
\nTo use this guide, you need:
\nNOTE: 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.
\nThe BIMS API uses the open OAuth 2.0 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.
\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.
\nWhat we've just described is an authenticated access token, because it's tied to a particular user who has an Identity of BIMS.
\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.
\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.
\nFor the purposes of the BIMS API, the only supported grant type for now is authorization code.
\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.
\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.
\nHere are the general steps:
\nStep 1. Send your end user to the authorization URL.
\nStep 2. Receive access permission from your end user.
\nStep 3. Get the authorization code.
\nStep 4. Send us the authorization code.
\nStep 5. Get the access token.
\nDirect your end user to the following address:
\nhttps://bims.tetfund.gov.ng/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}&scope={scope_list}\n\nSee the table below for details about the query parameters.
\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.
As 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.
Once they accept, we send them to the redirect URI, along with the code and state query parameters, for example;
\nhttps://your-app.com/redirect-url?code={code}&state={state}\n\nSee the table below for more information.
\nNOTE: We retain any custom query parameters that you include with your URI.
\nYou now have the authorization code that you can exchange for an access token, so make a POST request to /oauth/token:
POST https://bims.tetfund.gov.ng/oauth/token\n\nThe headers to send appear in the table below.
\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.
You can get your app's client identifier and client secret from your dashboard, which you will also add to the request body.
\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\nSee the table below for descriptions of common errors.
\nThe API responds with the access token and details about the authenticated user (see the section below).
\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\nNOTE: There are 5 user types that can be returned. A list and brief description will be given for each below:
\nadmin: 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*
\nstudent: This user type refers to a student of an institution and the user data returned includes an Institution ID and data.
\nlecturer: This user type refers to an Academic staff of an institution and the user data returned includes an Institution ID and data.
\nstaff: This user type refers to a Non-Academic staff of an institution and the user data returned includes an Institution ID and data.
\nclient: 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.
\nAdditionaly, you can also get the user by the access token generated from number 5 above.
\nPOST https://bims.tetfund.gov.ng/oauth/userinfo\n\nThe headers to send appear in the table below:
\nThe API then responds by getting the user authenticated from the access token. See the response structure below:
\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\nhttps://account.bims.ng/clients/BIMS-23-Q2EXXN/users/BIMS23AD50234/logout?redirect_to={my_redirect_url}\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:
\nREDIRECT your user to the above url from within your application.
\nThe 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.
NOTE: The host for this particular request is different from the other requests in this documentation, i.e https://account.bims.ng
Typically, 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.
You may want to add the BIMS logo to this button for a better visual experience.
You may Download the BIMS logo here.
This endpoint makes an HTTP GET request to retrieve user data with optional pagination parameters. The per_page parameter specifies the number of users per page which can be set on the first call, and the cursor parameter is used for fetching the next set of results for subsequent calls
The response returns a status indicating the success of the request, along with a message and an array of user data. Each user object includes details such as ID, name, type, email, gender, and institution information. Pagination URLs for the next and previous pages are also provided in the response.
\nAs an alternative to setting the cursor parameter, the next_page_url should be called for every returning response along with the previous query parameters to get the next page of users list.
Example response:
\n![Download the BIMS logo here](\"https://bims.tetfund.gov.ng/img/logo.png\"){kind=link}
{\n \"status\": true,\n \"message\": \"\",\n \"data\": [\n {\n \"id\": 0,\n \"bims_id\": \"\",\n \"first_name\": \"\",\n \"middle_name\": null,\n \"last_name\": \"\",\n \"type\": \"\",\n \"email\": \"\",\n \"gender\": \"\",\n \"dob\": null,\n \"photo\": \"\",\n \"institution\": {\n \"id\": 0,\n \"short_name\": \"\",\n \"name\": \"\"\n }\n }\n ],\n \"per_page\": 5000,\n \"next_page_url\": \"https://bims.tetfund.gov.ng/api/users?cursor=eyJ1c2Vycy5pZCI6NzQ3LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9\",\n \"prev_page_url\": null\n}\n\nThis endpoint shows the information of a single user who has been authorized for the client applicationx.
\n","urlObject":{"path":["users","BIMS2369STD34070"],"host":["https://bims.tetfund.gov.ng/api"],"query":[],"variable":[]}},"response":[{"id":"7da8e6df-f93e-41da-9b08-ef9e15fe5306","name":"Get a user","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"","value":"","type":"text","disabled":true}],"url":"https://bims.tetfund.gov.ng/api/users/BIMS2370STD50234"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 13 Jul 2022 12:03:31 GMT"},{"key":"Server","value":"Apache/2.4.52 (Unix) OpenSSL/1.1.1m PHP/8.1.2 mod_perl/2.0.11 Perl/v5.32.1"},{"key":"Vary","value":"Authorization"},{"key":"X-Powered-By","value":"PHP/8.1.2"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"57"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Length","value":"576"},{"key":"Keep-Alive","value":"timeout=5, max=100"},{"key":"Connection","value":"Keep-Alive"},{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": true,\n \"title\": \"\",\n \"message\": \"User retrieved\",\n \"data\": {\n \"user\": {\n \"id\": 52,\n \"bims_id\": \"BIMS2370STD50234\",\n \"first_name\": \"John\",\n \"middle_name\": \"Guy\",\n \"last_name\": \"Doe\",\n \"type\": \"student\",\n \"email\": \"johndoe@example.com\",\n \"photo\": \"https://res.cloudinary.com/myskoolp/image/upload/c_fill,g_face,h_220,w_220/v1/bims/photos/bqjsqsczgf78zjecvtw4.jpg\",\n \"institution\": {\n \"id\": 69,\n \"short_name\": \"FCEYOLA\",\n \"name\": \"Federal College Of Education Yola\"\n }\n }\n }\n}"}],"_postman_id":"9ed28e9c-130f-4d1c-9d3e-1bd42cf51002"}],"id":"38e9bbd8-c914-4c40-8630-3fd75a5950cb","description":"This API allows you to make user specific requests.
\n","_postman_id":"38e9bbd8-c914-4c40-8630-3fd75a5950cb","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"12618c3b-e9ca-4b6e-bf16-5a4f2759a2db","id":"12618c3b-e9ca-4b6e-bf16-5a4f2759a2db","name":"Client API","type":"folder"}}},{"name":"Get Token","id":"c0491abc-1a76-4a3e-a277-9e9137511ee5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"email\": \"lyte.onyema@krystalng.com\",\n \"password\": \"kdns4231\"\n}","options":{"raw":{"language":"json"}}},"url":"https://bims.tetfund.gov.ng/api/auth/login","description":"This endpoint generates the authorization token required to make authenticated requests to the client api.
\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"12618c3b-e9ca-4b6e-bf16-5a4f2759a2db","id":"12618c3b-e9ca-4b6e-bf16-5a4f2759a2db","name":"Client API","type":"folder"}},"urlObject":{"path":["auth","login"],"host":["https://bims.tetfund.gov.ng/api"],"query":[],"variable":[]}},"response":[{"id":"e26d9d90-989d-4c84-9cfc-1edf0b6527e3","name":"Get Token","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"email\": \"lyte.onyema@kdns.com\",\n \"password\": \"password\"\n}","options":{"raw":{"language":"json"}}},"url":"https://bims.tetfund.gov.ng/api/auth/login"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.22.1"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept-Encoding"},{"key":"X-Powered-By","value":"PHP/8.2.15"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Sun, 28 Jan 2024 16:29:51 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"phpdebugbar-id","value":"X2c2d011f7289de12e3a2b625a439b5e7"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": true,\n \"message\": \"\",\n \"data\": {\n \"user\": {\n \"id\": 968,\n \"bims_id\": \"BIMS2369CL47404\",\n \"name\": \"Lyte Onyema\",\n \"email\": \"lyte.onyema@kdns.com\",\n \"client\": [\n {\n \"id\": \"BIMS-22-04LS94L\",\n \"institution_id\": 69,\n \"name\": \"FCE Yola EduZone LMS\",\n \"institution\": {\n \"id\": 69,\n \"name\": \"Federal College Of Education Yola\",\n \"short_name\": \"FCEYOLA\"\n }\n }\n ]\n },\n \"token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJCSU1TLTIzLVJVMzlRWiIsImp0aSI6IjUzZTI0NzA2ODBhNjYzMGY3MDg4ODgwM2M5NjMzOTAxMmM5ZWY4ZDkxMmU4NjYwMmQ1NDA1ZGFmNmQyMDEzOTk2NTUwYWJhODA0ZmQxNmI4IiwiaWF0IjoxNzA2NDU5MzkxLjg2MTA4MSwibmJmIjoxNzA2NDU5MzkxLjg2MTA4MiwiZXhwIjoxNzM4MDgxNzkxLjg1NjI3MSwic3ViIjoiOTY4Iiwic2NvcGVzIjpbXX0.obCU7IKf--SsNxmXv4WLlXuH9gDLTC2Ofc1iUK1hJ6D42bEb2M2tHqAP4zcIpxsWe4nFxTYkNiwvQyP21W85vB7PBc6CT86ufUkPx94ciYoY0b531aHwZSuumUXpyYDFqT51Rn4uH-Vw3_y4NvDyP-IMuRpNwEpSskq5-FgZ8l5M-34fQQb2k7y8N5a5fNA1r35AWd-DKvaIhnccG1Ym9XsvBazu1U2pvMGX0_E05WFHs6sEYB9iwXLlj2qzehmk5EhNiVAA_TQm0bcDupJpcJXa9b7xPi0dMVi_dJS1zOoEl_2mmQffxbr8CXOjT9ofqAx1g2_z4rH1RZWTMgmpLlxDzqhYDKiR44ipV7y758adkeOoBqugR8RjypwV_KrWfaPClYh2VaBqc5xLKmufXpc0EsiwiNULSFzr-l6KROBbWHyiUkjHO-1Zy9_7Pz7Ai9JC9WF0PotaRETHVLSRrJzh3lbwZzBhBCOzRA788wv9UHrA--76O8mavsk9B--8mhCrlQcP1wokgW3k_dWlWcAq6F1yzuZGVILnabXypctprCD9NoGtRLan1qBkB_F-04xD0SW6CS25fadRYDO4K7PYs_337lRL9WZk_5Xg_LpZYjuigjkGZW9oNSJwTj-qU5rOd9oavKzf6no2RZ3MAUcIc3Jr78CMUxwmf4BTCP0\"\n }\n}"}],"_postman_id":"c0491abc-1a76-4a3e-a277-9e9137511ee5"}],"id":"12618c3b-e9ca-4b6e-bf16-5a4f2759a2db","description":"This api provides access to the client user to make specific requests to meet their needs.
\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"ed168911-e3c3-462e-a3e5-be3144cf5649","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"8632e3ed-aada-4a0e-b197-cb93bdf0ffcb","type":"text/javascript","exec":[""]}}],"_postman_id":"12618c3b-e9ca-4b6e-bf16-5a4f2759a2db"},{"name":"List Institutions","id":"c1a6e36b-5770-46f8-8a96-3f80cbbfc1d9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://bims.tetfund.gov.ng/api/institutions","urlObject":{"path":["institutions"],"host":["https://bims.tetfund.gov.ng/api"],"query":[],"variable":[]}},"response":[{"id":"ce56c29b-5261-4074-8d2d-2260a119247f","name":"List Institutions","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://bims.tetfund.gov.ng/api/institutions"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.23.3"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept-Encoding"},{"key":"X-Powered-By","value":"PHP/8.2.10"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 14 Dec 2023 17:10:19 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"phpdebugbar-id","value":"X0d8b67a799658f10850b949875c8c6db"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": true,\n \"message\": \"Fetched Institutions.\",\n \"data\": [\n {\n \"id\": 3,\n \"name\": \"Abdu Gusau Polytechnic Talatamafara\",\n \"short_name\": \"AGPOLY\",\n \"email\": null,\n \"state\": \"ZAMFARA\",\n \"zone\": \"NORTH-WEST\",\n \"address\": null,\n \"logo\": null\n },\n {\n \"id\": 252,\n \"name\": \"Abia State College of Education (Technical), Arochukwu\",\n \"short_name\": \"ASCETA\",\n \"email\": null,\n \"state\": \"ABIA\",\n \"zone\": \"SOUTH-EAST\",\n \"address\": null,\n \"logo\": null\n },\n {\n \"id\": 4,\n \"name\": \"Abia State Polytechnic Abia\",\n \"short_name\": \"ABIAPOLY\",\n \"email\": null,\n \"state\": \"ABIA\",\n \"zone\": \"SOUTH-EAST\",\n \"address\": null,\n \"logo\": null\n },\n {\n \"id\": 197,\n \"name\": \"Abia State University\",\n \"short_name\": \"ABSU\",\n \"email\": null,\n \"state\": \"ABIA\",\n \"zone\": \"SOUTH-EAST\",\n \"address\": null,\n \"logo\": null\n },\n {\n \"id\": 5,\n \"name\": \"Abraham Adesanya Polytechnic Ijebu Igbo\",\n \"short_name\": \"AAPII\",\n \"email\": null,\n \"state\": \"OGUN\",\n \"zone\": \"SOUTH-WEST\",\n \"address\": null,\n \"logo\": null\n }\n ]\n}"}],"_postman_id":"c1a6e36b-5770-46f8-8a96-3f80cbbfc1d9"}],"event":[{"listen":"prerequest","script":{"id":"506d0c8b-b1d6-4a62-b947-8bcda8ea10a7","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"60ad5dff-3de8-44bc-8b89-79e1ae3f40fb","type":"text/javascript","exec":[""]}}],"variable":[{"key":"baseURL","value":"https://bims.tetfund.gov.ng/api"},{"key":"localUrl","value":"bims-app.test/api","type":"string"}]}