Authentication
Users can login to your applications using the MOTAR SSO which will have full CAC support in Summer 2021
Reminder: if you are using an app/client ID in sandbox, you must use
sandbox.motar.io as the endpoint for your requests. Requests to api.motar.io with a sandbox client ID will fail!MOTAR Single Sign On buttons are available for authentication in your application. Please see Brand guidelines for MOTAR SSO.
Reminder: new apps connecting to MOTAR should use PKCE flow, as it offers more security. MOTAR may deprecate Implicit flow in the future.
To authenticate a MOTAR user in a 3rd party app, you will need to follow the MOTAR OAuth flow. Before beginning this process, you will need to have an app created with a client ID and secret, as well as a registered redirect UI in MOTAR Studio.
If your app is a standalone web client, you can use MOTAR's OAuth flow to render a login screen in a web client. Note that if you're app is launched from the MOTAR Dashboard, you should authenticate using a redirect auth code. If your app is not launched from the MOTAR Dashboard and you cannot render a webview, you can use Basic Auth.
First, display a MOTAR auth screen to the user. Use your client ID to identify your application to the user and enter the URI you wish the auth screen to redirect the user to upon auth completion.
For production:
GET https://api.motar.io/oauth/signin?response_type=code
&client_id=<CLIENT_ID>
&redirect_uri=<REDIRECT_URI>
&state=NONCE
For sandbox:
GET https://sandbox.motar.io/oauth/signin?response_type=code
&client_id=<CLIENT_ID>
&redirect_uri=<REDIRECT_URI>
&state=NONCE
state: a string value provided by the web server application that maintains state between the authorization request and the MOTAR server response. The value will be returned as a request parameter to the redirect URI and should be validated by the web server. This may be a nonce or base64 encoded object with information relevant for the web server application.
In response to the authorization request, a web page login form for MOTAR is displayed. The user logs in and decides whether or not to allow to your app. After the user decides, MOTAR will redirect to the redirect URI provided in the initial request.
GET <REDIRECT_URI>?code=AUTH_CODE&state=NONCEIn the case of a failed login or denial of permissions, an error is returned:
GET <REDIRECT_URI>?error="User cancelled request."Your application should be configured to handle these parameters.
Next, your application should use the AUTH_CODE from the redirect above to generate an auth token to use with the MOTAR API.
For production:
POST https://api.motar.io/oauth/token?grant_type=authorization_code
&code=<AUTH_CODE>
&client_id=<CLIENT_ID>
&client_secret=<CLIENT_SECRET>
For sandbox:
POST https://sandbox.motar.io/oauth/token?grant_type=authorization_code
&code=<AUTH_CODE>
&client_id=<CLIENT_ID>
&client_secret=<CLIENT_SECRET>
You will need your Client Secret in addition to your client ID in this step.
How to Generate "AUTH_CODE": If you're launching your app from a MOTAR Dashboard lesson, the dashboard can generate an auth code. Make sure your app has a Desktop Launch URI set in MOTAR Studio, and check the "Pass authentication code with redirect" box which is listed on the Desktop Launch URI window. This will tell the MOTAR Dashboard to pass a "code" query parameter in the launch redirect that can be used in the above request.
The response from MOTAR will be in the following JSON format:
{
"access_token": "<ACCESS_TOKEN>",
"refresh_token": "<REFRESH_TOKEN>",
"expires_in": "1d",
"token_type": "Bearer"
}
- access_token - the MOTAR access token to use in API calls. Use this token in the "Authorization" header as follows:
Authorization: Bearer <ACCESS_TOKEN>. The access token uniquely identifies the logged in user and your app on the MOTAR platform. - refresh_token - once the access token expires, the web server application can retrieve a new one with the refresh token (see below).
- expires_in - length of life for the access token before it must be refreshed (see below).
After this step is complete, the user is officially logged into the MOTAR platform and can use the API as normal using their access token.
When the access token expires (defined by the expires_in field), it must be refreshed for the user to continue to use the API.
Make a call to the token URL to refresh an access token (production):
POST https://api.motar.io/oauth/token?grant_type=refresh_token
&refresh_token=<REFRESH_TOKEN>
&client_id=<CLIENT_ID>
&client_secret=<CLIENT_SECRET>
Sandbox:
POST https://sandbox.motar.io/oauth/token?grant_type=refresh_token
&refresh_token=<REFRESH_TOKEN>
&client_id=<CLIENT_ID>
&client_secret=<CLIENT_SECRET>
This is the only request that requires a refresh token. All other requests should only include the access token in the Authorization header unless otherwise specified by the API docs.
A refresh token uniquely identifies a session and a device for a user. You should not re-use this token across multiple sessions/devices.
For security reasons, the MOTAR API uses a relatively short access token life of 24 hours. Since access tokens only a short period of time, your app will need to refresh them to maintain usability. There are generally two strategies for determining when to refresh a token.
With this strategy, your app will need to keep track of when the access token was generated, and perform a refresh before this timer expires. This is the preferred method, as it reduces the chances of retry errors.
Alternately, apps can automatically refresh an access token when the API indicates that the token has expired. The API will return the following when a client attempts to use an expired token:
401: Unauthorized
body: {
"error_description": "Token refresh required",
"error_code": 4010
}
The "error_description" and "error_code" are also included in response headers if the response body is unavailable.
At this point, the client should pause its request, refresh the access token, and then retry with the refreshed access token.
Make sure you pause or queue all other requests until the refresh is complete!
Reminder: The authentication 'code' is passed in the redirect when a user launches a lesson from a MOTAR course. The code will expire so use it immediately to generate your user auth token.
Last modified 10d ago