Obtaining an Access Token with Password Grant Type
Learn how to authenticate using your username and password, and get an access token for subsequent API requests.
This operation authenticates a user in the system based on the Client ID and client credentials. It returns an access token that will be used in other API requests.
Request
POST https://auth.reltio.com/oauth/token| Name | Required | Description | |
|---|---|---|---|
| Headers | Authorization
| Yes | The Basic authentication header, provided by Reltio with a specific set of client credentials. |
Content-Type | Yes | application/x-www-form-urlencoded | |
| Body Parameters | username
| Yes | A username of the end user registered in the Reltio database. |
password
| Yes | A password of the end user registered in the Reltio database. | |
grant_type
| Yes | Type of access token request. The value is: password. | |
Response
If authentication is successful, the response will contain a JSON object with the following structure:
| Property | Required | Description | Type |
|---|---|---|---|
| Yes | Access token that should be used for any upcoming requests to any Reltio API. | String |
token_type
| Yes | Type of OAuth2 token. For the Reltio Auth server, it is always Bearer (additional information about the Bearer token type can be found here ). | String |
| Yes | This value will be used for refreshing expired access token. For more information, see Refresh Token. | String |
| Yes | Time period in seconds when the access token is valid. When the access token expires, it needs to be refreshed. For more information, see Refresh Token. | String |
entityURI
| URI of an entity object that is associated with the authenticated user. | String | |
scope
| Yes | An array of access scopes for which the access token is valid. In our implementation we have the following scopes:
| Array of Strings |
Obtaining an Access Token with Password Grant Type
Authenticate using your username and password to obtain an access token for subsequent API requests. The process involves making a POST request to the Reltio Auth server with specific headers and body parameters.
The headers required include the Authorization and Content-Type. The body parameters include the username, password, and grant_type. Upon successful authentication, a JSON object is returned containing properties such as access_token, token_type, refresh_token, expires_in, entityURI, and scope.
It's important to note that tokens expire after 60 minutes. Therefore, it's recommended to store the token and use it until it expires, then get a new one. Exceeding the limit of 10 GET token requests per second will result in a 429 HTTP status (Too Many Request) message. To avoid this, enable the Multi Token Support feature.
403 Forbidden error.
Request
POST https://auth.reltio.com/oauth/token
Headers:Authorization:Basic cmVsdGlvX3VpOnNlY3JldA==
Content-Type: application/x-www-form-urlencoded
Body:password=<password>&username=<username>&grant_type=passwordResponse
{
"access_token":"204938ca-2cf7-44b0-b11a-1b4c59984512",
"token_type":"bearer",
"refresh_token":"676742af-989b-4d40-b7cc-f69ccadd45ea",
"expires_in":3599,
"scope":" configuration_api entities_api graphs_api groups_api interactions_api relations_api
} Token API request limit
By default, tokens expire after 60 minutes. To authenticate into Reltio using scripts or integrations, you must get a token, store it, and use it until it expires. Get a new token after the current one expires.
If you don't store your token, you will need to request a token every time you want to authenticate into Reltio. This is a highly inefficient practice. In Reltio, we have a limit of 10 GET token requests per second. If you exceed this limit, you will see the 429 HTTP status (Too Many Request) message. This indicates that you need to change the way you are requesting tokens to ensure it complies with our limit.