Version: v2

Absorb Integration API

Download OpenAPI specification:Download

Overview

Many of the resources in a client portal are protected and require that the user is authenticated. The Absorb Integration API uses openId connect (authorization code flow) to provide an access token and refresh token.

This token must then be sent in the Authorization header when making requests to protected resources.

Authorization: Bearer <token>

Access token is valid for 4 hours after it is issued. After the time has elapsed, another login request is required to get a new token.

Refresh token lasts for 1 year.

As the token represents an authenticated user, it must be protected. Bearer authentication should only be used over HTTPS; Absorb LMS does not support HTTP.

OAuth Authorization Code Flow

1. Request Auth Code

To request an authorization code, user makes an authentication request to authorization endpoint. Please note that the authorization code is 1-time use

Header is not required for requesting an authorization code. This call is not made via postman but entered into a browser.

Name	Type	Description
client_id	string	The unique API client identifier. Location: Portal Settings -> Integration API OAuth Client ID
client_secret	string	The unique API client secret identifier. Location: Portal Settings -> Integration API OAuth Client Secret
redirect_uri	string	The URI the users are sent back to after authorization. Should always be https.
response_type	string	The value of this field should always be "code".
scope	string	Space-delimited list of member permissions your application is requesting. Supported scope: "admin.v1"
state	string	A unique string value of your choice that is hard to guess.

It will redirect to the login page for the user to login. If the login is successful, the consent page will pop up. After the user provides the consent, the server will redirect to the URL provided in the redirect_uri query parameter and provide the authorization code.

/* Example */

https://clientRoute.com/oauth/authorize?client_id=_ahKweh2tdKdNMKnecwo&client_secret=iBHVbc0fn7vdCgvMxDAy7fWNlpQCwAcQoeCNYEDboahcUime01&redirect_uri=https://example.com&response_type=code&scope=admin.v1&state=anyString

2. Get Refresh Token

Exchange an authorization code for a refresh token. Make a request to token endpoint, providing the authorization code received in the previous step.

POST rootUrl/oauth/token

Headers

Name	Description
x-api-version	The value of this header should always be "v1".

Body

Name	Type	Description
grant_type	string	The value of this field should always be "authorization_code".
client_id	string	Portal Settings -> Integration API OAuth Client ID
client_secret	string	Portal Settings -> Integration API OAuth Client Secret
code	string	The authorization code received in previous step.
nonce	string	String value used to associate a client session with an ID Token, and to mitigate replay attacks
redirect_uri	string	The URI the users are sent back to after authorization. Should always be https.

The following is an example of a successful token response.


{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im9HZTc1M0VNdVhFUFhmQ1hKUWlxaHZhNHUxbyIsIng1dCI6Im9HZTc1M0VNdVhFUFhmQ1hKUWlxaHZhNHUxbyIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6ImNlMDI3N2EyLTFmMGQtNGRlYi1hZGY3LTJkMGQ2ODQ3YWM2ZCIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL25hbWUiOiJjZTAyNzdhMi0xZjBkLTRkZWItYWRmNy0yZDBkNjg0N2FjNmQiLCJ1c2VySWRlbnRpdHkiOiJ7XCJJc1N5c3RlbUlkZW50aXR5XCI6ZmFsc2UsXCJVc2VySWRcIjpcImNlMDI3N2EyLTFmMGQtNGRlYi1hZGY3LTJkMGQ2ODQ3YWM2ZFwiLFwiTmFtZVwiOlwiY2UwMjc3YTItMWYwZC00ZGViLWFkZjctMmQwZDY4NDdhYzZkXCIsXCJBYnNvcmJBdXRoZW50aWNhdGlvblR5cGVcIjo2LFwiQXV0aGVudGljYXRpb25UeXBlXCI6XCJUb2tlblwiLFwiSXNBdXRoZW50aWNhdGVkXCI6dHJ1ZSxcIkRlcGFydG1lbnRJZFwiOm51bGx9IiwiY2xpZW50UG9ydGFsSWRlbnRpdHkiOiJ7XCJSb3V0ZUlkXCI6XCJmNTJjNTQyOC1hNDM4LTQwN2ItODc2MC0wMzU3Y2NmMzFkMzBcIixcIkNsaWVudElkXCI6XCIwMDAwMDAwMC1hYWFhLWJiYmItNTU1NS0wMDAwMTIxMmJiYmJcIixcIkRlcGFydG1lbnRJZFwiOlwiMjgzZDhmOGQtZWUwZi00Yjk5LWFjYzYtY2QyZjYxYTYyZWRhXCIsXCJJc0RlcGFydG1lbnRTcGVjaWZpZWRCeVJvdXRlXCI6ZmFsc2V9IiwiYWNjZXNzTW9kZSI6IlwiQXBpXCIiLCJzY29wZSI6IltcImFkbWluXCIsXCJsZWFybmVyXCJdIiwib3BlbklkU2NvcGUiOiJbXCJvcGVuaWRcIl0iLCJub25jZSI6InRlc3QiLCJuYmYiOjE2MjAyNTUyMjgsImV4cCI6MTYyMDI2OTYyOCwiaWF0IjoxNjIwMjU1MjI4LCJpc3MiOiJodHRwczovL215YWJzb3JiLmNvbS8iLCJhdWQiOiJodHRwczovL215YWJzb3JiLmNvbS8ifQ.j_BMGj5x9JYT0Il2wL3OOrEdVkfhzayVOIMO9PLRfuC9buVJnJcQ4p56ddken8X1Hrj4dEe3vyKYyPFv6pyvGEqmVVScqLfgQ-HPffjeVzsN6nRuXiYyWp4bBUYQTvmX5R497s-a_0K79YXrRjxFe0UCFZ4p1uL9A4VuJ4xvVcXMMeTYDkEZl-owhrfn_uhpLfWpIhTUDO0vQryoLtcpocd_MddK5Cd4ctDVfN0boFx9emCSK3mWhck7Tyu9f2UQsKmZHqGZaAwJuZ-fgni8KDBH6kon7V0_JKQeglZSuvDLih4yO7GgIcfEvWS4YyhRc3C2a4xuCaNatw0vIC18GQ",
    "token_type": "bearer",
    "expires_in": 14399,
    "refresh_token": "09RR0D5mp5J56i4GTPEjdhMyMhw6t5IhTad5ErDD"
}

Name	Type	Description
access_token	string	The access token for the application.
token_type	string	The type of this access token.
expires_in	string	The number of seconds remaining until the token expires.
refresh_token	string	The refresh token, can be used to acquire new access tokens.

3. Get Access Token

Recreate an access token using a refresh token to login on behalf of a given user. Access tokens only last 4 hours. Once access token is expired, you can use the refresh token to acquire a new access token. You can also use refresh token to acquire an access token on behalf of another learner.

POST rootUrl/oauth/token

Headers

Name	Description
x-api-version	The value of this header should always be "v1".

Body

Name	Type	Description
grant_type	string	The value of this field should always be "refresh_token".
client_id	string	Portal Settings -> Integration API OAuth Client ID
client_secret	string	Portal Settings -> Integration API OAuth Client Secret
refresh_token	string	The refresh token issued by the server in previous step.
nonce	string	String value used to associate a client session with an ID Token, and to mitigate replay attacks
on-behalf-of	string	(Optional) The username of another user you would like to be logged in as
scope	string	Space-delimited list of member permissions your application is requesting. Supported scope: "admin.v1"

4. Make Request Using Access Token

Once you've obtained an access token, you can start making authenticated API requests by including an Authorization header in the HTTP call.

/* Example */

GET my-profile
Authorization Bearer {access_token}

If you are using the access token on behalf of another user, you will see the info of the user you are on behalf of in the response.

OAuth

Request Authorization Code

Make an authentication request to authorization endpoint to get an authorization code.

query Parameters

client_id required	string <string> The unique API client identifier. Location: Portal Settings -> Integration API OAuth Client ID
client_secret required	string <string> The unique API client secret. Location: Portal Settings -> Integration API OAuth Client Secret
redirect_uri required	string The URI the users are sent back to after authorization. Should always be https.
response_type required	string The value of this field should always be "code".
scope required	string Space-delimited list of member permissions your application is requesting.
state required	string A unique string value of your choice that is hard to guess.

Responses

Get Refresh Token / Access Token

Make request to get an refresh token or get a token on behalf of user. Please refer to "OAuth Authorization Code Flow" part 2 and 3 for more details about different types of requests.

Authorizations:

x-api-key

header Parameters

x-api-version

required

string

Request Body schema: x-www-form-urlencoded

The request to get an access/refresh token or get an access token on behalf of a user.

grant_type	string The value of this field should always be "authorization_code" or "refresh_token".
client_id	string Portal Settings -> Integration API OAuth Client ID
client_secret	string Portal Settings -> Integration API OAuth Client Secret
nonce	string String value used to associate a client session with an ID Token, and to mitigate replay attacks. Code property is only used in the get refresh token call.
code	string The authorization code received in oauth/authorize step. Code property is only used in the get refresh token call.
on-behalf-of	string Username you want to sign in as. On behalf of property is only used in the on-behalf-of call call.
refresh_token	string Refresh token from get refresh token oauth/token call Refresh token property is only used in the on-behalf-of call call.
scope	string Space-delimited list of member permissions your application is requesting. Scope property is only used in the on-behalf-of call call.

Responses

Response Schema: application/json

access_token	string Access token that represents an authenticated user. It is required by protected API endpoints. The token must be included in the `Authorization` header in the format: `Authorization: Bearer [token]`
token_type	string This value will always be "bearer".
expires_in	int The number of seconds remaining until the token expires.
refresh_token	string The refresh token, can be used to acquire new access tokens.

Response samples

Content type

application/json

{"access_token": "string",
"token_type": "string",
"expires_in": null,
"refresh_token": "string"
}