Legacy Identity tokens API v4

This document refers to the legacy token service available via the identity-service. For all new work, please use the OAuth2.1 compliant service available from the accesso-authoization-service. See OAuth2 Access Tokens for more information.

accesso provides an OAuth2-compliant endpoint capable of authenticating against multiple systems. Upon successful authentication, the endpoint returns a JSON Web Token, or JWT, which may be used as a means of authenticating against accesso's APIs.

JSON Web Tokens

accesso’s services issue tokens in the form of JSON Web Tokens, or JWT. Learn more about JWTs and list libraries for working with JWTs.

Tokens API

accesso’s Tokens API is an OAuth2-compliant set of endpoints which enables an authorized user to receive a JWT needed for accesso’s APIs.

The API supports authentication and re-authentication against users stored in accesso’s database as well as users authenticated by federated providers such as Authentic and OpenAM.

The Tokens v4 API supports requests using the password grant, refresh grant, and client-credential grant for anonymous tokens. On success, this endpoint will return an accesso Token object which will contain a JSON Web Token (JWT). All requests to the v4 tokens endpoint can be URL encoded (application/x-www-form-urlencoded) per the OAuth2 standard but can also be in JSON format.

Regardless of the type of authentication, a successful authentication results in an HTTP response status of 200 and the following response payload:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
    "access_token": "eyJhbGciOiJSUz...",
    "token_type": "bearer",
    "refresh_token": "eyJhbGciOiJSUzI1Ni...",
    "expires_in": 86399,
    "scope": "authenticated openid",
    "account_id": "user@yourcompany.com",
    "user_type": "Guests",
    "venueId": null,
    "organization": "your-company",
    "amr": [
        {
            "authority": "credential"
        }
    ],
    "iss": "https://www.theexperienceengine.com/",
    "phone_number": null,
    "source": "UNKNOWN",
    "iat": 1576075405,
    "email": "user@yourcompany.com",
    "uuid": "404589da-7a39-4e9c-8697-ce05fb57449e",
    "jti": "ec2488b7-f364-437c-a640-204670b9c44d"
}

Notable fields above include:

The JWTs returned from the tokens API contain all of the data that is also returned in plaintext. It is only necessary to retain the access and refresh tokens.

Authentication types

Anonymous

As there are cases where the caller does not have the information needed to fully authenticate, such as a password, accesso’s Identity APIs provide anonymous tokens. Anonymous tokens are tokens which are associated with a user but not with any credential or personally identifying information (e.g. email). When an anonymous token is requested, a new user is inserted into the database. The ID of the user is then returned along with a valid access token and valid refresh token.

Form URL Encoded

1
2
3
4
5
6

curl --location --request POST 'https://api.{region}.te2.io/v4/tokens' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {apiKey}' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=anonymous'

JSON version

1
2
3
4
5
6
7
8

curl --location --request POST 'https://api.{region}.te2.io/v4/tokens' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {apiKey}' \
--data-raw '{
	"grant_type": "client_credentials",
	"scope": "anonymous"
}'

Parameters used above include:

Required properties

Optional properties

Required headers

Because requesting an anonymous token inserts a record into the database, you should request an anonymous token only when absolutely necessary.

Password

Password grant is used in cases where accesso stores a user’s login credentials, such as an email-password combination. The format of this type of authentication is as follows:

1
2
3
4
5
6
7
8

curl --location --request POST 'https://api.{region}.te2.io/v4/tokens' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {apiKey}' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={accountId}' \
--data-urlencode 'password={credential}' \
--data-urlencode 'scope={requested-scope}'

Parameters used above include:

Required properties

Optional properties

Required headers

Federated

In cases where the customer requires a custom Federated solution, a custom grant can be defined for the Federated authentication provider. For some customers, accesso serves as a proxy to another authentication system. That is, accesso is given an account identifier, such as an email, and the actual credential of that account. accesso then forwards the identifier and credential to the third-party authentication system. Accesso then receives a customer-generated token is which is used as a credential to obtain an accesso JWT. The custom_token name of the grant shown below will be customer-specific and must be configured by the accesso implementation team. This JWT response will not contain an ‘openid’ scope.

1
2
3
4
5
6

curl --location --request POST 'https://api.{region}.te2.io/v4/tokens' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {apiKey}' \
--data-urlencode 'grant_type=custom_token' \
--data-urlencode 'custom_token={custom-credential-token}'

Parameters used above include:

Required properties

Required headers

accesso never records or logs the credential of an account when using federated authentication.

Refresh

Access tokens issued by accesso expire after 24 hours. These tokens can be reissued, or refreshed, at any time by using the refresh token which was issued alongside the access token. Refreshing will issue both a new access token as well as a new refresh token.

1
2
3
4
5
6

curl --location --request POST 'https://api.{region}.te2.io/v4/tokens' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {apiKey}' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={credential}'

Parameters used above include:

Required properties

Required headers

Unlike most OAuth2 systems, refresh tokens issued by accesso expire after 90 days. At refresh, the caller should always replace their held access and refresh tokens with the new tokens returned.

Service Tokens

The Service Token request is the same as the password grant request, with the added requirement that a scope of ‘admin’ must be requested to indicate that this is a service account with elevated privileges. Documentation regarding service tokens can be found in the Service accounts and service tokens guide.

Additional optional headers

There are several headers which have not been covered in any of the examples above. These headers have special purpose, including specifying which user tags are set and allowing a user to migrate between devices. The following headers are optional on all the variations of the tokens API examples above.

Best practices

  Do:

  Don’t:

Need help? Search our documentation or contact your assigned Client Engagement Manager.

Terms of use

© 2020 accesso Technology Group, plc.

All Rights Reserved.