Access Tokens API
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.
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
This method offers the following 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
When this method runs, it can pass in an optional request object that contains two attributes, as shown below:
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
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:
{
"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
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
This method offers the following 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
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
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:
Response Object
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:
{
"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
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
This method offers the following 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
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
Not applicable.
Response Object
The response object returned by this method contains only a status value-pair for the transaction. Consider the following sample:
Statuses and Errors
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.