Access Tokens

Authentication

Access Tokens

The Oauth2 service generates access tokens for authenticated users, applications or companies. The token returned in the Oauth2 response can be used to access protected resources on Turium Enigma services.

The Oauth2 response can, depending on grant type contain these values:

Name	Type	Format	Description
expires_in	string	-	The lifetime in seconds of the access token
scope	string	-	The scope of the access token as granted to the client application
token_type	string	-	The type of token returned. Value will be Bearer
access_token	string	-	Token used to access protected resources of Turium Enigma services.
refresh_token	string	-	Refresh token required to request a new access token for a given user.
geolocation	string	-	The base URL for where the user profile lives.
id_token	string	-	The OIDC Token in the JSON Web Token (JWT) format that describes the user or company

Token Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "oidc_token"
}

Obtaining a token

You can obtain a token for three different types of principals in the Turium Enigma universe.

• User

• Application

• Company

Token Lifetime

An accessToken has a one hour lifetime.

In order to obtain a token, the client application needs to call the Oauth2 endpoint using various grants depending on the authentication scenarios required.

Refreshing a token

The refresh grant is used to refresh an access_token that has expired. This grant can be used anytime a refresh_token is returned in the response of another grant request. No user interaction is required.

Token Lifetime

A refresh token has a six month lifetime. If the refresh token expires, the client application must reinitiate the authorization process. When a refresh token is used to request a new access token, both a new access token as well as a new refresh token are returned in the response. This token can change even if most of the time, this value is the same. Client applications should treat all returned refresh tokens as new tokens and overwrite the stored tokens with the new token from the response.

It is recommended that the client application use the refresh grant to request a new access token as the initial step of accessing protected resources of Turium Enigma services.

Refreshing the token

To request a new access token using a valid refresh token, use the Oauth2 /token endpoint. Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Name	Type	Format	Description
client_id	string	UUID	Required The client applications client_id supplied by App Management
client_secret	string	UUID	Required The client applications client_secret supplied by App Management
refresh_token	string	-	Required An existing valid refresh token to be used to request a new access token
scope	string	-	Optional The client applications list of scopes
grant_type	string	-	Required The grant type instructs the Oauth2 service how to process the request. For refresh token, the value must be refresh_token

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=refresh_token
&refresh_token=valid-refresh_token
&scope=app-scope

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "oidc_token"
}

When the token has been refreshed, store the geolocation and the refresh token as they may have changed. On subsequent calls, use the last received geolocation and refresh token.

Revoking a token

All refresh tokens associated to a user for an application can be revoked by calling the endpoint with a DELETE action. You have to provide the User’s accessToken in the Authorization Header as Authorization: Bearer <access_token>.

Request

DELETE 
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

Managing tokens

Refresh Tokens are strings that allow your application to obtain a fresh accessToken on behalf of a user to access Turium Enigma APIs. The exact format of the string can change, but may look similar to the following:

e013335d-b4ce-4c43-a7e4-b67abc1adcb0

or like this:

2d725xipty0z7ha3vlpy8b2c3hqxmw

It is highly recommended that you store Refresh Tokens together with your user’s authorization metadata in your application every time you obtain a new refreshToken as they might change depending on different scenarios.

FOR APP CENTER AND SUPPLIER PARTNERS supporting all geolocations, storing the authorization metadata, including the geolocation are REQUIRED.

Base URIs

When making API calls, the appropriate base URI should be used. There are three different scenarios:

1. Obtaining a token for a user.

2. Refreshing a token.

3. Calling other APIs.

The base URI for obtaining a token will leverage your application’s geolocation. The base URI for refreshing tokens and all other API calls will leverage the token’s geolocation.

Base URIs for Obtaining a Token

When your application is created, you will be provided with a client ID, secret and geolocation. When obtaining a token, your application should use the base URI for the geolocation in which your application exists.

There are two endpoints for each geolocation - one is the default (used for server-side calls) and the other should be used for client-side calls.

When obtaining the token, the token’s geolocation will be included in the response. The token’s geolocation should be stored along with the token. The Developer’s app will then be able to make subsequent calls using the token and the correct end points based on the token’s GEO location.

Base URIs for All Other Calls

When refreshing a token or when calling any other APIs, the token’s geolocation should be used as the base URI.

Note: Client-side calls should use the www- variant of the base URI.

Example

Consider an example where your application obtains a token and receives the response below:

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "oidc_token"
}

When your application calls another API, such as the receipts API to post a receipt, the request should be made using the base URI specified in the geolocation value of the response. The geolocation value can be any of the supported base URIs. The application should store the specific geolocation it receives, and use it as the base URI for future API calls when using that token.

ID Token

Authentication service will return an OPENID compatible ID token with every token request. This id_token is primarily used to describe information about a user or a company. You can obtain the userId from this token.

Verifying an id_token

The Authentication service exposes JWKs that can be used to validate the id_token in the form of a JWT. Validating a JWT is described in detail in RFC 7519 - sec 7.2

Authorization grant

The authorization grant is the regular 3-legged oauth2 grant and is defined in detail in RFC6749 sec-4.1. This grant requires the user to explicitly authenticate themselves and authorise the application initiating the grant.

The users must be able to authenticate themselves via a Turium Enigma username & password. Users will be challenged to login by an Oauth2 HTML page.

Who should use it

• 3rd party “partner” websites - or -

• non-Turium Enigma Applications - & -

• Applications that need explicit user authentication & authorization - & -

• Applications that can securely store a code, access_token & refresh_token

Grant details

Note that the grant type must be accessed using the www- version of the API Gateway in order to avoid certificate issues with some browsers.

GET /oauth2/v0/authorize

Name	Type	Format	Description
client_id	string	UUID	Applications client_id supplied by App Management
redirect_uri	string	-	The redirect URI for your application to continue with the Oauth2 flow
scope	string	-	List of scopes that application is asking for
response_type	string	-	code
state	string	-

With this grant, the user has two authentication options:

1. Username and password

2. One-time link using a verified email address

With both options, once the user is successfully authenticated and the user authorizes your application, the user will be redirected to the redirect_URI specified in the initial /authorize call with a temporary token appended.

<redirect_uri>?geolocation=<token_geolocation>&code=<token>

If the user is not successfully authenticated or does not authorize the scopes for your application, an error code and description will be appended to the redirect URI.

Your application must then exchange the temporary token for a long-lived token using the below.

POST /oauth2/v0/token

Name	Type	Format	Description
client_id	string	UUID	Applications client_id supplied by App Management
client_secret	string	UUID	Applications client_secret supplied by App Management
redirect_uri	string	-	The redirect_uri that is registered for the application
code	string	UUID	The authorization code provided by Auth
grant_type	string	-	authorization_code

Password grant

The Password grant can be used when there is a trust relationship between the user and the application. There are two credential types allowed with Password Grant:

1. “Password”: with this credential type, the application either already has the user’s credentials or can obtain the user’s credentials by directly interacting with the user.

2. “AuthToken”: This credential type is used for connections.

Post Body

Name	Type	Format	Description
client_id	string	UUID	Applications client_id supplied by App Management
client_secret	string	UUID	Applications client_secret supplied by App Management
grant_type	string	-	Specify which grant type you expect the oauth2 service to process. for password grant, the value is password
username	string	-	specify the username or userId
password	string	-	specify the user’s password
credtype	string	-	The credtype signifies to oauth2 which credential set is being submitted in the request. There are two supported values: authtoken and password. For connections from the App Center, use authtoken. if omitted, oauth2 will assume the type is password.

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Connection: close
Content-Length: 175

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=username
&password=password

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "oidc_token"
}

example bad login

{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}

Client Credentials grant

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Name	Type	Format	Description
client_id	string	UUID	Required Applications client_id supplied by App Management
client_secret	string	UUID	Required Applications client_secret supplied by App Management
grant_type	string	-	Required Specify which grant type you expect the oauth2 service to process. For client_credentials grant, the value is client_credentials

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Connection: close
Content-Length: 127

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=client_credentials

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1626
Connection: Close

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token"
}

One Time Password grant

The One-time Password grant type leverages email, phone (text messaging), instant messaging and similar systems to provide per user access tokens to client applications. This grant type requires the following steps:

1. The calling application calls the OAuth2 service specifying the otp grant type along with required parameters.

2. The OAuth2 service generates a one time token which it sends through the messaging mechanism chosen by the application.

3. The user retrieves the token and presents it to the application. The means of having this presented to the application is the responsibility of the application.

4. The application presents this one-time token to the OAuth2 service via the token endpoint.

Request a one-time token to be sent to the user

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/otp

Post Body

Name	Type	Format	Description
client_id	string	UUID	Required The client_id as defined in the Turium Enigma application management system.
client_secret	string	UUID	Required The client_secret as set by the client owner in the Turium Enigma application management system.
channel_handle	string	-	Required The location (email address, phone number) where the one time token should be sent. Currently, only email address is valid.
channel_type	string	-	Required The type of messaging system to use. Currently only email is valid
name	string	-	Optional The name of the user that appears in the email.
company	string	-	Optional The company or application name that appears in the email.
link	string	-	Optional The callback URL that appears in the email for users to click to complete the auth flow.

The calling application code can also append n-number of unique client defined parameters in the URI for the purpose of connecting the one time token to the application when received by the user. The names of these parameters cannot conflict with the API defined parameters.

The following are reserved words and cannot be used as client application defined parameters:

/otp: "client_id" "client_secret" "channel_type" "channel_handle"

/token: "client_id" "client_secret" "channel_type" "channel_handle" "scope" "grant_type" "otp"

If the calling application chooses to send custom parameters, all of these exact same parameters must be included in subsequent API calls to acquire the access token. In other words, the URI signature, modulo the one time token parameter itself and token service specific parameters, must match the originating URI signature.

Request

POST /oauth2/v0/otp HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&link=https://example.com/callback

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 22
Date: date-requested

{
  "message": "otp sent"
}

Request an access token

The One Time Password grant requires that all of the parameters, including client application defined parameters to be sent in the request body when requesting an access token. Use the application/x-www-form-urlencoded content type.

POST oauth2/v0/token

Post Body

Name	Type	Format	Description
client_id	string	UUID	Required The client_id as defined in the Turium Enigma application management system.
client_secret	string	UUID	Required The client_secret as set by the client owner in the Turium Enigma application management system.
channel_handle	string	-	Required The location (email address, phone number) where the one time token should be sent.
channel_type	string	-	Required The type of messaging system to use. Currently only email is valid
scope	string	-	The scope(s) requested by the client for the token.
grant_type	string	-	Required The grant type being used, specifically for this approach: otp.
otp	string	-	Required The one-time token provided as a result of the Send a one time token to the user method.

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&scope=app_scope
&grant_type=otp
&otp=one-time-token

Response

HTTP/1.1 200 OK
Date: date-requested
Content-Length: 1490
Connection: keep-alive

{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "oidc_token"
}

Response Codes

HTTP Status returned by oauth2

HTTP Status	Description
200	OK - Successful call, response is in body.
400	Bad Request (error, error_description, code)
401	Unauthorized (error, error_description, code)
403	Forbidden (error, error_description, code)
404	Not Found (error, error_description, code)
500	Server Error, error message is in body.
503	Server Timed Out, error message is in body.

4xx class errors have a JSON response with the following fields

{
  "code": <number>,
  "error": <error>,
  "error_description": <error_description>,
  "geolocation": <geolocation url where user lives>
}

/authorize

If the authorization or authentication are unsuccessful, your application will receive an error code and description at the redirect_uri provided.

 error_code=<>
 &error_description=<>

In all cases, the friendly error description should be displayed to the user.

/token

Code	Error	Description
5	invalid_grant	Incorrect credentials. Please Retry
10	invalid_grant	Account is disabled. Please contact support
11	invalid_grant	Account is disabled. Please contact support
12	invalid_grant	Logon Denied. Please contact support
13	invalid_grant	Logon Denied. Please contact support
14	invalid_grant	Account Locked. Please contact support
16	invalid_request	user lives elsewhere
19	invalid_grant	Incorrect credentials. Please Retry
20	invalid_grant	Logon Denied. Please contact support (typically due to IP restriction)
51	invalid_request	username was not supplied
52	invalid_request	password was not supplied
53	invalid_client	company is not enabled for this client
54	invalid_scope	requested scope exceeds granted scope
55	invalid_request	we don’t know this email
56	invalid_request	otp was not supplied
57	invalid_request	channel_type missing
58	invalid_request	channel_handle missing
59	access_denied	client disabled
60	invalid_grant	these are not the grants you are looking for
61	invalid_client	client not found
62	invalid_request	client_id was not supplied
63	invalid_request	client_secret was not supplied
64	invalid_client	Incorrect credentials. Please Retry
65	invalid_request	grant_type was not supplied
80	invalid_request	invalid channel type
81	invalid_request	bad channel handle
83	invalid_request	otp not found
84	invalid_request	fact verification failed
85	invalid_request	otp verification failed
100	invalid_request	backend does not know about this username
101	invalid_request	code was not supplied
102	invalid_request	redirect_uri was not supplied
103	invalid_request	code is bad or expired
104	invalid_grant	redirect_uri does not match the previous grant
105	invalid_grant	this grant was not issued to you!
106	invalid_request	refresh_token was not supplied
107	invalid_request	refresh disallowed for app
108	invalid_grant	bad or expired refresh token
109	invalid_request	loginid was not supplied
115	invalid_request	unauthenticated client will not be issued token!
117	invalid_request	nonce is mandatory for this response_type
118	invalid_request	display is invalid
119	invalid_request	prompt is invalid
119	invalid_request	prompt must be set to consent for offline_access
120	invalid_request	credtype is invalid
121	invalid_request	login_type is invalid
122	invalid_request	proxies supplied are invalid
123	invalid_request	principal is disabled
134	invalid_request	Company undergoing scheduled maintenance.

/otp

Code	Error	Description
16	invalid_request	user lives elsewhere
57	invalid_request	channel_type was not supplied
58	invalid_request	channel_handle was not supplied
60	invalid_grant	these are not the grants you are looking for
61	invalid_client	client_id is not known to us
62	invalid_request	client_id was not supplied
63	invalid_request	client_secret was not supplied
80	invalid_request	invalid channel type
81	invalid_request	bad channel handle
82	invalid_request	the number of open otp requests has been exceeded

Troubleshooting

In order to assist with troubleshooting, Turium Enigma responds with a unique correlationId in the response header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the Turium Enigma support team.

Example of the correlationid in the response:

< HTTP/1.1 200 OK
< Server: cnqr-papeete
< Date: Mon, 04 Dec 2017 22:07:05 GMT
< Content-Type: application/json
< Content-Length: 2897
< Connection: keep-alive
< Correlationid: 2803b8f8-a42b-43c2-a739-b8768e4759b8