Access Tokens API
Grant customers login access with OAuth access tokens, and revoke a single token or every token for a customer.
This API has been scheduled for deprecation. Information on recommended alternatives is forthcoming. Please contact your customer success representative for more information.
Access Tokens can be used to grant login access to customers as well as invalidate those logins. When revoking these OAuth access tokens, you can delete either a specific token or all tokens for the customer.
This API provides a way to grant customers login access. The access tokens managed by the Access Tokens API can be revoked at any time, despite whatever time may be optionally specified for the token's TTL. When called, the delete routes servicing these tokens invalidate a token's related session cookie.
API Contingencies and Combinations:
- Since access tokens are assigned to a customer, you must create the customer that requires the token. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
- Before you can access a token, verify that you have permission for the appropriate access level. This permissions level is the same as the level required to create or modify a customer account.
This API facilitates the creation and deletion of access tokens. It provides the following methods:
Create an Access Token
Specify a request to create a new access token.
Endpoints for Create an Access Token
This method offers the following endpoints:
REST Endpoints
POST /priv/v1/apps/:api_key/users/:user_id/access_token
POST /priv/v1/apps/:api_key/external/users/:external_id/access_token
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoints Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object for Create an Access Token
When this method runs, it can pass in an optional request object that contains two attributes, as shown below:
JSON Request
{
"token": "token_string",
"expires_in": 3600
}
These attributes are detailed in the following table:
Request Attributes for Access Token
| Attribute | Type Required/Optional | Description |
|---|---|---|
| token | string optional | Unique identifier for the token. |
| expires_in | integer optional | Time to live (TTL) in seconds until the requested access token expires. |
Response Object for Create an Access Token
In addition to a status value-pair for the transaction, the response object returned by the method contains an access_token object.
Consider the following sample:
JSON Response
{
"access_token": {
"access_token": "access_token",
"created_at": 1518627262,
"expires_in": 1209600,
"refresh_token": "663792192674a527709a4e5d3ed1a9c0442d502bc2526633"
},
"status": "ok"
}
This object is detailed in the following table:
Response Attributes for Access Token
| Attribute | Type | Description |
|---|---|---|
| access_token | string | Unique identifier for the token. |
| created_at | integer | Unix timestamp of when the access token was created. |
| expires_in | integer | Time to live (TTL) in seconds until the access token expires. |
| refresh_token | string | OAuth refresh token. |
| revoked_at | string | Specifies the date and time the access token was revoked (deleted). Attribute appears only in the response object generated by the access token delete method. |
Statuses and Errors for Create an Access Token
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.
Revoke an Access Token
Revoke, or delete, an existing access token.
Endpoints for Revoke an Access Token
This method offers the following endpoints:
REST Endpoints
DELETE /priv/v1/apps/:api_key/access_token
DELETE /priv/v1/apps/:api_key/access_token?auth_token=xxxx
DELETE /priv/v1/apps/:api_key/access_token?access_token=xxxx
DELETE /priv/v1/apps/:api_key/access_token?token=xxxx
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters for Revoke an Access Token
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| auth_token | Authorization token to delete. |
| access_token | Access token to delete. |
| token | Token to delete. |
Request Object for Revoke an Access Token
When this method runs, it can pass in a required request object that contains one attribute, token_to_revoke, which is a string that identifies the access token to revoke and is shown below:
JSON Request
{
"token": "token_to_revoke"
}
Response Object for Revoke an Access Token
In addition to a status value-pair for the transaction, the response object returned by the method contains an access_token object.
Consider the following sample:
JSON Response
{
"access_token": {
"access_token": "access_token",
"revoked_at": "2018-02-14T16:55:15Z"
},
"status": "ok"
}
For more information on this response and its attributes, see the Response Attributes for Access Token table.
Statuses and Errors for Revoke an Access Token
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.
Revoke All Access Tokens
Revoke, or delete, all access tokens associated with a specific customer.
Endpoints for Revoke All Access Tokens
This method offers the following endpoints:
REST Endpoints
DELETE /priv/v1/apps/:api_key/users/:user_id/access_token
DELETE /priv/v1/apps/:api_key/external/users/:external_id/access_token
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters for Revoke All Access Tokens
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object for Revoke All Access Tokens
Not applicable.
Response Object for Revoke All Access Tokens
The response object returned by this method contains only a status value-pair for the transaction. Consider the following sample:
JSON Response
{
"status": "ok"
}
Statuses and Errors for Revoke All Access Tokens
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.