OAuth 2.0 Token Endpoint

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

POST /{tenant}/oauth2/v1/token

Exchanging an authorization code

Request

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

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]

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.

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.

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.

Name	Values	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.

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

Request

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

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]

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.

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.

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.

Name	Values	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.

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

Request

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

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]

Response

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

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.

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.

Name	Values	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.

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