OAuth 2.0 token endpoint API

This OAuth 2.0 endpoint can be used to exchange authorization codes, refresh tokens and to request an App token.

Exchanging an authorization code

POST /{tenant}/oauth2/v1/token

The request

Request parameters

Name Values Description Required
grant_type authorization_code This parameter indicates that the code sent is an authorization code. Yes
code The authorization code The authorization code you want to exchange Yes
client_id The Client ID you obtained from the Apps admin page The Client ID uniquely identifies your App. Yes
client_secret The Client Secret you obtained from the Apps admin page The Client ID and Client Secret are used to authenticate your App. Yes if available
redirect_uri One of the redirect uri's you configured for your app in the Apps admin page This parameter determines where the response is sent. This must exactly match one of the values listed for your App in the Apps admin page Yes
code_verifier Any string Proof Key for Code Exchange parameter. This parameter will be compared to the code_challenge that was provided on authorization code request. See https://tools.ietf.org/html/rfc7636. No unless authorization code was requested with PKCE

Example request

POST /{tenant}/oauth2/v1/token/ HTTP/1.1
Host: theidentityhub.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=X5678IYHI690UJJJ000
&client_id=[YOUR_CLIENT_ID]
&client_secret=[YOUR_CLIENT_SECRET]
&redirect_uri=[YOUR_APP_REDIRECT_URI]
&code_verifier=[CODE_VERIFIER]

The response

If the request was successfully validated, The Identity Hub will issue an access and refresh token. These values will be returned as a json result.

Response parameters

Name Values Description
access_token The access token as a string value This parameter holds the access token issued by The Identity Hub.
token_type bearer This value will always be "bearer" to indicate this is a bearer token.
expires_in A numeric value The number of seconds the access token is valid from the time it was issued.
scope A space delimited set of scopes The list of scopes that are returned, can be different from the list of scoped your App asked in the initial request. This can be the result of a user not granting the App access to certain scopes or changes in the rights of the user, that prevent the user from having the scopes.
refresh_token The refresh token as a string value The refresh token that can be used to request a new access token.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
    "access_token":"7779HHKHKHKK6683TY3",
    "token_type":"bearer",
    "expires_in":3600,
    "scope": "profile.read",
    "refresh_token":"703JH3YU89YH389T3878T38"
}

Handling errors

If the specified parameters of the request are invalid, The Identity Hub will respond with an error. The response is a json result.

Error parameters

Name Value Description
error invalid_grant The passed token or code was invalid, unknown or revoked.
invalid_client The client is unknown or blocked
unsupported_grant_type The value of the response_type parameter is not supported by The Identity Hub
invalid_scope One of the requested scopes is invalid.
unauthorized_client The client is not authorized to request a token or code using this method.

Example error response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
    
{ 
    "error":"invalid_request" 
}

Exchanging a refresh token

POST /{tenant}/oauth2/v1/token

The request

Request parameters

Name Values Description Required
grant_type refresh_token This parameter indicates that the code sent is an authorization code. Yes
refresh_token The refresh token as a string value The refresh token you want to exchange Yes
client_id The Client ID you obtained from the Apps admin page The Client ID uniquely identifies your App. Yes
client_secret The Client Secret you obtained from the Apps admin page The Client ID and Client Secret are used to authenticate your App. Yes if available

Example request

POST /{tenant}/oauth2/v1/token/ HTTP/1.1
Host: theidentityhub.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=X5678IYHI690UJJJ000
&client_id=[YOUR_CLIENT_ID]
&client_secret=[YOUR_CLIENT_SECRET]

The response

If the request was successfully validated, The Identity Hub will issue an access and refresh token. These values will be returned as a json result.

Response parameters

Name Values Description
access_token The access token as a string value This parameter holds the access token issued by The Identity Hub.
token_type bearer This value will always be "bearer" to indicate this is a bearer token.
expires_in A numeric value The number of seconds the access token is valid from the time it was issued.
scope A space delimited set of scopes The list of scopes that are returned, can be different from the list of scoped your App asked in the initial request. This can be the result of a user not granting the App access to certain scopes or changes in the rights of the user, that prevent the user from having the scopes.
refresh_token The refresh token as a string value The refresh token that can be used to request a new access token.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
    "access_token":"7779HHKHKHKK6683TY3",
    "token_type":"bearer",
    "expires_in":3600,
    "scope": "profile.read",
    "refresh_token":"703JH3YU89YH389T3878T38"
}

Handling errors

If the specified parameters of the request are invalid, The Identity Hub will respond with an error. The response is a json result.

Error parameters

Name Value Description
error invalid_grant The passed token or code was invalid, unknown or revoked.
invalid_client The client is unknown or blocked
unsupported_grant_type The value of the response_type parameter is not supported by The Identity Hub
invalid_scope One of the requested scopes is invalid.
unauthorized_client The client is not authorized to request a token or code using this method.

Example error response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
    
{ 
    "error":"invalid_request" 
}

Requesting an App token

POST /{tenant}/oauth2/v1/token

The request

Request parameters

Name Values Description Required
grant_type client_credentials This parameter indicates that an App token is requested. Yes
client_id The Client ID you obtained from the Apps admin page The Client ID uniquely identifies your App. Yes
client_secret The Client Secret you obtained from the Apps admin page The Client ID and Client Secret are used to authenticate your App. Yes if available

Example request

POST /{tenant}/oauth2/v1/token/ HTTP/1.1
Host: theidentityhub.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=[YOUR_CLIENT_ID]
&client_secret=[YOUR_CLIENT_SECRET]

The response

If the request was successfully validate, The Identity Hub will issue an access token. These values will be returned as a json result.

Response parameters

Name Values Description
access_token The access token as a string value This parameter holds the access token issued by The Identity Hub.
token_type bearer This value will always be "bearer" to indicate this is a bearer token.
expires_in A numeric value The number of seconds the access token is valid from the time it was issued.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"7779HHKHKHKK6683TY3",
    "token_type":"bearer",
    "expires_in":3600
}

Handling errors

If the specified parameters of the request are invalid, The Identity Hub will respond with an error. The response is a json result.

Error parameters

Name Value Description
error invalid_grant The passed token or code was invalid, unknown or revoked.
invalid_client The client is unknown or blocked
unsupported_grant_type The value of the response_type parameter is not supported by The Identity Hub
invalid_scope One of the requested scopes is invalid.
unauthorized_client The client is not authorized to request a token or code using this method.

Example error response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
    
{ 
    "error":"invalid_request" 
}

Related sections

How To: Perform OAuth Code Grant
How To: Perform OAuth Client Credentials Grant