Introduction

The Authentication API enables you to manage a user identity.

This API supports OpenID Connect and OAuth 2.0

Authentication methods

There are three ways to authenticate with this API:

with an OAuth2 Access Token in the Authorize request header field (which uses the Bearer authentication scheme)
with your Client ID and Client Secret
only with your Client ID

Each endpoint supports only one option.

OAuth2 Token

In this case, you have to send a valid Access Token in the Authorization header, using the `Bearer authentication scheme. An example is the Get User Info endpoint

Client ID and Client Secret

In this case, you have to send your Client ID and Client Secret information in the request body. This option is only available for confidential applications (such as applications that are able to hold credentials in a secure way without exposing them to unauthorized parties).

Client ID

For public applications (such as applications that cannot hold credentials securely, like SPAs or mobile apps), there are some endpoints that can be accessed using only the Client ID. An example is the Implicit Grant.

Parameters

For GET requests, parameters can be passed as an HTTP query string parameter.

For POST requests, parameters not included in the URL should be form url encoded with a Content-Type of application/x-www-form-urlencoded.

Authorize Application

To begin an OAuth 2.0 Authorization flow, your application should first send the user to the authorization URL.

The purpose of this call is to obtain consent from the user to invoke the API (specified in audience) and do certain things (specified in scope) on behalf of the user.

The OAuth 2.0 flows that require user authorization are:

Authorization Code Grant
Implicit Grant

On the other hand, the Client Credentials flow does not use this endpoint since there is no user authorization involved. Instead it invokes directly the POST /oauth/token endpoint to retrieve an Access Token.

Based on the OAuth 2.0 flow you are implementing, the parameters slightly change.

Authorization Code Grant

GET/oidc/authorize

GET /oidc/authorize?
  audience=API_IDENTIFIER&
  scope=SCOPE&
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://YOUR_APP/callback&
  state=STATE
  acrValues=ACR

webAuth.authorize({
  audience: "API_IDENTIFIER",
  scope: "SCOPE",
  clientID: "YOUR_CLIENT_ID",
  responseType: "code",
  redirectUri: "https://YOUR_APP/callback",
  state: "STATE",
  acrValues: "ACR",
})

Response Sample

HTTP/1.1 302 Found
Location: https://YOUR_APP/callback?code=AUTHORIZATION_CODE&state=STATE

This is the OAuth 2.0 grant that traditional server-side web apps utilize in order to access an API.

Request Parameters

Parameter	Required	Description
`audience`	optional	The unique identifier of the target API you want to access.
`scope`	optional	The scopes which you want to request authorization for. These must be separated by spaces. You can request any of the standard OIDC scopes about users such as `profile` and `email`. Include `offline_access` to get a Refresh Token.
`response_type`	required	Indicates which OAuth 2.0 flow you want to perform. Use `code` for the Authorization Code Grant Flow.
`client_id`	required	Your application's ID.
`tenant`	recommended	Your tenant's slug. Required if the application is associated with more than one tenant.
`state`	recommended	An opaque value the application adds to the initial request that Identity Service includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks.
`redirect_uri`	optional	The URL to which Identity Service will redirect the browser after authorization has been granted by the user.
`prompt`	optional	To initiate a silent authentication request, use `prompt=none`. To force the user to always enter their credentials even if they have an existing session, use `prompt=login`.
`acr_values`	required	A value indicating the level of assurance (LOA) you require from IDS. This value determines how far IDS will go to be sure of the identity of the user logging in (e.g. a username and password, two-factor authentication, passwordless over SMS...). Defaults to username and password. For more details and a list of values, click here

Implicit Grant

GET/oidc/authorize

GET /oidc/authorize?
  audience=API_IDENTIFIER&
  scope=SCOPE&
  response_type=token|id_token|id_token token&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://YOUR_APP/callback&
  state=STATE&
  nonce=NONCE&
  acr_values=ACR

webAuth.authorize({
  audience: "API_IDENTIFIER",
  scope: "SCOPE",
  clientID: "YOUR_CLIENT_ID",
  responseType: "id_token token",
  redirectUri: "https://YOUR_APP/callback",
  state: "STATE",
  nonce: "NONCE",
  acrValues: "ACR",
})

Response Sample

HTTP/1.1 302 Found
Location: https://YOUR_APP/callback#access_token=TOKEN&state=STATE&token_type=TYPE&expires_in=SECONDS

This is the OAuth 2.0 grant that mobile apps and client-side web apps (such as SPAs) utilize in order to acecss an API.

Request Parameters

Parameter	Required	Description
`audience`	optional	The unique identifier of the target API you want to access.
`scope`	optional	The scopes which you want to request authorization for. These must be separated by spaces. You can request any of the standard OIDC scopes about users such as `profile` and `email`. Include `offline_access` to get a Refresh Token.
`response_type`	required	Indicates which OAuth 2.0 flow you want to perform. Use `token` to get only an Access Token, `id_token` to get only an ID Token (if you don't plan on accessing an API), or `id_token token` to get both and ID Token and an Access Token.
`client_id`	required	Your application's ID.
`tenant`	recommended	Your tenant's slug. Required if the application is associated with more than one tenant.
`state`	recommended	An opaque value the application adds to the initial request that Identity Service includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks.
`redirect_uri`	optional	The URL to which Identity Service will redirect the browser after authorization has been granted by the user.
`nonce`	required	A string value which will be included in the ID Token response. This should be used to prevent replay attacks.
`prompt`	optional	To initiate a silent authentication request, use `prompt=none`. To force the user to always enter their credentials even if they have an existing session, use `prompt=login`.
`acrValues`	required	A value indicating the level of assurance (LOA) you require from IDS. This value determines how far IDS will go to be sure of the identity of the user logging in (e.g. a username and password, two-factor authentication, passwordless over SMS...). Defaults to username and password. For more details and a list of values, click here
`color`	optional	Hex code representation of a color to override the default primary theme color (e.g. A69A22).

ACR Values

Authentication Context Class Reference (ACR) values let you request a certain level of assurance (LOA) from IDS that the user being authenticated is actually who they say they are. In other words, this value is what determines how rigorous of a login process users will be required to go through. A low LOA would be passwordless SMS login, for example, where a user enters their phone number and is sent a code which they then enter to log in. A high LOA would be two-factor authentication, where a user not only has to provide their username and password, but also has to provide a code from an authentication app on their mobile device.

The values are related to each other in a heirarchical manner - higher LOAs satisfy the requirements of lower LOAs. Thus the value you request is a minimum requirement; for instance, if you request a LOA of username and password, but a user signs in with two-factor authentication, they will be successfully authorized. But if they try to sign in with a social auth provider, they will not be authorized.

This concept also applies to Single Sign On (SSO) between different applications using IDS. If someone is already logged in through IDS at a certain LOA, they will be authorized to access any application requesting a equal or lower LOA without needing to sign in again.

A full list of supported ACR values is below. You can send any one value with an authorization request.

Value	Description
`ids:loa:none`	Indicates that the user was signed in with only a username, email or phone #. No confidence.
`ids:loa:0`	Indicates that the user was signed in via a long-lived browser cookie (e.g. social auth)
`ids:loa:1`	Indicates that the user was signed in with a SMS code
`ids:loa:2`	Indicates that the user was signed in with a single factor, e.g. username/password or email code
`ids:loa:3`	Indicates the user was signed in with an app-based soft token and a minimum of two factors
`ids:loa:pci:nc`	Indicates the user was signed in with a method compliant with PCI DSS third-party, non-consumer user. This enforces PCI requirements such as requiring users to update their passwords every 90 days, and disabling users after 90 days of inactivity.

Get Token

Use this endpoint to:

Get an Access Token in order to call an API.
Refresh your Access Token, using a Refresh Token you got during authorization.

Authorization Code

POST/oauth/token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2FYOUR_APP%2Fcallback

Response Sample

{
  "access_token": "q4nSM29R...8sJUCM",
  "refresh_token": "VrbRdxNa...eSdosL",
  "id_token": "eyJz93a...WFWmXA",
  "token_type": "Bearer",
  "expires_in": 3600
}

This is the OAuth 2.0 grant that regular web apps utilize in order to access an API. Use this endpoint to exchange an Authorization Code for a Token.

Request Parameters

Parameter	Required	Description
`grant_type`	required	Denotes the flow you are using. For Authorization Code use `authorization_code`.
`client_id`	required	Your application's ID.
`client_secret`	required	Your application's Client Secret.
`tenant`	recommended	Your tenant's slug. Required if the application is associated with more than one tenant.
`code`	required	The Authorization Code received from the initial `/oidc/authorize` call.

Client Credentials

POST/oauth/token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
audience=API_IDENTIFIER&grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Response Sample

{
  "access_token": "q4nSM29R...8sJUCM",
  "token_type": "Bearer",
  "expires_in": 3600,
  "audience": "API_IDENTIFIER"
}

This is the OAuth 2.0 grant that server processes utilize in order to access an API. Use this endpoint to directly request an Access Token by using the Client Credentials (a Client ID and a Client Secret).

Request Parameters

Parameter	Required	Description
`grant_type`	required	Denotes the flow you are using. For Client Credentials use `client_credentials`.
`client_id`	required	Your application's ID.
`client_secret`	required	Your application's Client Secret.
`audience`	required	The unique identifier of the target API you want to access.
`tenant`	optional	The identifier of the organization (tenant) whose data you want to interact with. This will default to your organization. To use a different organization other than your own, your application must have been granted access to that organization.

Refresh Token

POST/oauth/token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN

Response Sample

{
  "access_token": "q4nSM29R...8sJUCM",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid offline_access",
  "id_token": "eyJz93a...WFWmXA"
}

Use this endpoint to refresh an Access Token using the Refresh Token you got during authorization.

Request Parameters

Parameter	Required	Description
`grant_type`	required	Denotes the flow you are using. For Refresh Token use `refresh_token`.
`client_id`	required	Your application's ID.
`client_secret`	required	Your application's Client Secret.
`tenant`	recommended	Your tenant's slug. Required if the application is associated with more than one tenant.
`refresh_token`	required	The Refresh Token to use.

Password Grant Flow

POST/oauth/token

POST /oauth/token
Content-Type: application/json
{
  "grant_type": "password",
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Response Sample

{
  "access_token": "q4nSM29R...8sJUCM",
  "token_type": "Bearer",
  "expires_in": 3600
}

This is the OAuth 2.0 grant that server processes utilize in order to access an API. Use this endpoint to directly request an Access Token by using the Password Grant Flow (a Username and a Password).

Request Parameters

Parameter	Required	Description
`grant_type`	required	Denotes the flow you are using. For Password Grant Flow use `password`.
`client_id`	required (if the client was issued a secret)	Your application's ID.
`client_secret`	required (if the client was issued a secret)	Your application's Client Secret.
`tenant`	recommended	Your tenant's slug. Required if the application is associated with more than one tenant.
`username`	required	Your Username.
`password`	required	Your Password.

User Profile

Get User Info

GET/api/userinfo

GET /api/userinfo
Authorization: 'Bearer {ACCESS_TOKEN}'

webAuth.client.userInfo(accessToken).then(function (user) {
  // Now you have the user's information
})

Response Sample

{
  "sub": "6da3774c-da6a-4009-85c5-7920afd84af8",
  "given_name": "John",
  "family_name": "Doe",
  "email": "[email protected]",
  "email_verified": "true"
}

Given the Access Token obtained during authorization, this endpoint returns a user's profile.

This endpoint will only work if openid was granted as a scope for the Access Token.

Request Parameters

Parameter	Required	Description
`access_token`	required	The Access Token obtained during authorization.