---
title: Authorization
slug: authorization
docTags: 
createdAt: 2023-11-17T03:57:12.546Z
---

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](https://dashboard.throughlinecare.com), is described below.

## 1 - Get Client Application Credentials

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!

:::hint{type="warning"}
**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](docId\:kEr6xzB7ZAoBVRzkp9i3L) 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.
:::

## 2 - Generate an Access Token

To generate an access token, your application needs to send a POST request to the `oauth/token`endpoint with a `Content-Type `header of `x-www-form-urlencoded` and the following parameters in the request body:

:::BlockQuote
https\://api.findahelpline.com/oauth/token
:::

| **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**

```curl
curl --location --request POST 'https://api.findahelpline.com/oauth/token'
--form 'client_id="YOUR_CLIENT_ID"'
--form 'client_secret="YOUR_CLIENT_SECRET"'
--form 'grant_type="client_credentials"'
```

A successful access token request returns a JSON object containing the following fields:

- `access_token`: A JWT access token for the application. This token must be kept secure. Its length is variable, so be sure to store it in non-character-limited storage (it may be quite long).
- `token_type`: How the token is to be used.
- `expires_in`: Seconds until token expiration. Currently the default lifespan is 2 hours from issuance. Your application must request a new token before your current token expires. Do not hard-code this lifespan as the default may change without notice; your application should read the lifespan live and act accordingly.
- `scope`: public by default. There are no other available scopes at this time for the resources available in the ThroughLine API.

```json
{
    "access_token": "ABC....",
    "token_type": "Bearer",
    "expires_in": 7200,
    "scope": "public",
    "created_at": 1700452443
}
```

## 3 - Make API Requests

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**

```curl
curl --location --request GET 'https://api.findahelpline.com/api/v1/countries' \
--header 'Authorization: Bearer {access_token}
```

For more information on keeping your application calls to the API secure, please see our [API Security](docId\:kEr6xzB7ZAoBVRzkp9i3L) article.