Authorization
ThroughLine utilizes OAuth to authenticate requests to the API. It has been designed to be used in a server-to-server scenario in which requests are performed as a service rather than an individual user. This scenario is sometimes referred to as two-legged OAuth or application-only OAuth.
The basic flow for the ThroughLine API, using the application credentials you can retrieve from the Developer Dashboard, is described below.
In the developer dashboard create a new application or view the secrets for an existing one.
Each application is assigned a unique Client ID (Consumer key/API key) and Client Secret. Please make a note of these values as they will be integrated into your application config files. Your Client Secret protects your application's security so be sure to keep it secure!
Keep your secrets safe! Please safeguard your application secret. Do not share your Client Secret value with anyone, and do not pass it in the URL when making API calls, include it in URI query-string parameters, or post it in support forums, chat, etc. The secret is required to authenticate to the API and generate the tokens required to make valid calls to the API. See our API Security article for the best practices in keeping your calls to the API secure.
ThroughLine reserves the right to revoke any application credentials at any time and issue a new one if they have been leaked or misused.
To generate an access token, your application needs to send a POST request to the oauth/tokenendpoint with a Content-Type header of x-www-form-urlencoded and the following parameters in the request body:
Parameter | Description | Required |
|---|---|---|
grant_type | The value of this field should always be client_credentials | Yes |
client_id | The Client ID value generated when you registered your application | Yes |
client_secret | The Client Secret value generated when you registered your application | Yes |
Example Request
A successful access token request returns a JSON object containing the following fields:
- access_token: The access token for the application. This token must be kept secure.
- token_type: How the token is to be used.
- expires_in: Seconds until token expiration.
- The access token has a lifespan of 2 hours by default and should be used immediately. Your application requests a new token once your current token expires.
- scope: public by default. There are no other available scopes at this time for the resources available in the ThroughLine API.
Once you've received an access token, you can make API requests by including an Authorization header using the Bearer scheme with your token in the HTTP call to ThroughLine's API.
Example Request
For more information on keeping your application calls to the API secure, please see our API Security article.