Calling Protected Resources From Outside the Max Platform
To call protected resources from outside the Max platform, you obtain application client IDs which you then use to get access tokens with client IDs and user login credentials. You use these access tokens to call protected resources.
Access tokens are valid only for a limited time. If you use an expired access token to make a request to the resource server, Invalid Token Errors occur. If applicable, you can use a refresh token that was included when the original access token was issued to request a new access token from the authorization server.
Refresh tokens have longer lifetimes than access tokens, Max administrators can configure these lifetime values. When refresh tokens expire, applications must redirect users to the OAuth server to reauthorize, after which the OAuth server returns new access and refresh tokens.
Currently, implicit grants based on browser logins and resource owner password grants are supported. For resource owner password grants, refresh tokens are returned for clients (external applications) that have the refresh_token grant type. For implicit grants, per the specification, refresh tokens should not be issued. Refresh tokens are issued only in the following scenarios:
• The host name in redirect_uri is identical to the tenant hostname.
• The redirect_uri schema must not be HTTP or HTTPS. Typically, it is a mobile application (Android or iOS) schema.
Getting Application Client IDs
• Do one of the following:
◦ In the Advanced REST Client, send a GET request to https://<host>/oauth/client, and then check the Response Headers section for the Client Id value.
 |
To avoid 404 errors, ensure that no cookies are cached in the tenant.
|
◦ Alternatively, in Chrome Developer Tools, go to https://[hostname]/oauth/client, and then on the Network tab, check the Response Headers section.
Getting Access Tokens With Client IDs and User Login Credentials
• In the Advanced REST Client, send a POST request to https://<host>/sec/auth/token with the following name-value pairs in the payload (not the headers):
◦ client_id: The relevant application client ID.
◦ username: Username for access to protected resources from outside of Max.
◦ password: Password for access to protected resources from outside of Max.
◦ grant_type: password.
|
|
If you are using your local environment, send a POST request to https://localhost:7070/auth/token.
|
The returned UUID is the Record ID of the User record associated with the access token.
Calling Protected Resources With Access Tokens
1. In the Advanced REST Client, call a protected resource with the following name-value pair in the headers:
Authorization: Bearer <previously retrieved access token>
|
|
If a CSRF issue occurs, get the CSRF token at https://[hostname]/resources/js/csrf_script.
|
2. Add an X-CSRF-Token header with the token to the request.
OAuth Refresh Token Process
Refresh Token Flow
Refresh Access Token Process
When access tokens expire, applications must send refresh token requests to the OAuth server.
Request Format
POST https:///auth/token
For example, https:///sec/auth/token.
Parameter | Description |
|---|---|
grant_type | Must be refresh_token. |
refresh_token | Refresh token previously received by the client application. |
client_id | Client ID of the external application. |
| | All parameters must be URL-encoded. |
Request Example
curl https://mydomain.io/sec/auth/token -d "grant_type=refresh_token&client_id=57d22b28e0c5962541889195&refresh_token="
Request Response
Valid requests must meet the following criteria:
• The grant_type is refresh_token.
• The client_id is valid.
• The refresh_token exists and belongs to the client_id used in the request.
• The refresh_token has not expired.
If these criteria are met, the OAuth server sends a new access token to the application in JSON format. Otherwise, one of the following errors occurs.
Status Code | Response Body | Description |
|---|---|---|
400 | {"error":"invalid_request"} or {"error":"invalid_grant"} | Bad request, missing required parameters, or grant_type is not refresh_token. |
400 | {"error":"invalid_client","error_description":"client is invalid"} | Client does not exist. |
401 | {"error":"invalid_token","error_description":"invalid token provided"} | The refresh token does not exist, is expired, or does not belong to the client_id. |
200 | {"access_token":"new access token","token_type":"bearer","expires_in":86400} | New access token issued. |
Revoking Tokens
Request Format
POST https://<host>/sec/auth/token/revoke
For example, https://<server>/sec/auth/token/revoke.
If you are using your local environment, use https://localhost:7070/auth/token/revoke.
Parameter | Description |
|---|---|
token | Access token or refresh token to be revoked. |
client_id | Client ID to which this token was issued. |
token_type_hint | Token type (optional). |
Response Status Codes
Status Code | Message |
|---|---|
200 | Token revoked. |
400 | Bad request, token parameter is not provided, or client id is not provided. |
500 | Server error, or any error that occurred when querying or revoking access or refresh tokens. |
Open Issues
• Access tokens expire in 24 hours. This is hard-coded and nonconfigurable in system settings.
• Access tokens are stored in mongodb. There is no admin UI with which to review and manually delete or deactivate previously granted access tokens.
Request Format
POST https://<host>/sec/auth/token/revoke
For example, https://<server>/sec/auth/token/revoke.
In your local environment, use https://localhost:7070/auth/token/revoke.
Parameter | Description |
|---|---|
token | Access token or refresh token to be revoked. |
client_id | Client ID to which this token was issued. |
token_type_hint | Token type (optional). |
Response Status Codes
Status Code | Message |
|---|---|
200 | Token revoked. |
400 | Bad request, token parameter is not provided, or client id is not provided. |
500 | Server error, or any error that occurred when querying or revoking access or refresh tokens. |
Open Issues
• Access tokens expire in 24 hours. This is hard-coded and nonconfigurable in system settings.
• Access tokens are stored in mongodb. There is no admin UI with which to review and manually delete or deactivate previously granted access tokens.
For more information: