API authentication
This guide will teach you how to generate an access token and how to make a request to an Altrata GraphQL API endpoint.
The access token is a string which contains the credentials and permissions that can be used to access a given resource.
To generate an access token, you will need to make a HTTP POST request to https://api-auth.altrata.com/oauth2/token
In the request, you will need to specify the following:
Property | Parameter | Value | Description |
|---|---|---|---|
grant_type | Query | 'client_credentials" | The OAuth2 grant type that is used to obtain an access token |
x-api-key | Header | yourApiKey | You will need to enter your assigned API key as the value |
Authorization | Header | username:password | Basic Auth is used for the authorization. If you are making a request via Curl, you can supply your username:password. If you are using a backend language/framework such as Node.js, you will need to ensure that your username and password is base64 encoded when making a request to obtain an access token. See the Node.js example on the right to see how to potentially base64 encode your credentials. |
Once you have made a successful request to obtain an access token, you will get back a 200 response code that contains your bearer access token.
The token is a JSON Web Token. The expiration time for the tokens is set at 28800 seconds which is the equivalent of 8 hours. Once 8 hours has passed, the token will have expired and you will need to request a new token.
Please note that if you request a new token before the 8 hours have passed on your existing access token, you will be issued with a new token that will terminate your previous token. This means that you will not be able to use your previous access tokens to make calls to any Altrata API.
Store your access token in a secure location.
Now that you have generated an access token, you will need to do the following to to access the GraphQL endpoint:
If you are unsure of a GraphQL URL for a service(s), please visit the Services page that outlines all URLs
Set your HTTP method to be a POST request.
Set the URL to be the GraphQL endpoint that you wish to make a request to.
Include both x-api-key and Authorization header. Provide your api key as the value in the x-api-key header, and set the valueBearer and include your access token for the Authorization header.
