> For the complete documentation index, see [llms.txt](https://docs.raalabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raalabs.io/getting-started/authentication.md).

# Authentication

All API requests must be authenticated using OAuth 2.0 **Client Credentials** flow. You will need to obtain a **Client ID** and **Client Secret** to generate an access token from Raa Labs' authentication service. This access token (a JSON Web Token) encapsulates the permissions (scopes) for your client, determining which time series data you are allowed to access. Include the token in the header of every API request.

## API Credentials

**Client ID** and **Client Secret** are the credentials for your API client. After you obtain these, use them to request an access token. The token grants access to the time series data permitted for your client.

| Key               | Description                                             |
| ----------------- | ------------------------------------------------------- |
| **Client ID**     | The identifier for your client (use as `client_id`)     |
| **Client Secret** | The secret key for your client (use as `client_secret`) |

{% hint style="danger" %}
**Important:** Handle your **Client ID** and **Client Secret** with care. **Do not share or**\
**expose these credentials** in source code, public repositories, or unsecured locations. If you suspect that a Client Secret has been compromised, contact Raa Labs support immediately to regenerate it. Generating a new secret will invalidate the old one and block any requests made with the old secret. *(This action is irreversible.)*
{% endhint %}

### Obtaining API Credentials

To get a Client ID and Secret for the Raa Labs API, please contact our support team. You can request credentials by emailing <support@raalabs.com>. Raa Labs will provide the necessary credentials for your client.

### Getting an Access Token

Use the OAuth 2.0 Client Credentials grant to obtain an access token. This is done by making a POST request to the authentication endpoint with your **Client** **ID** and **Client Secret**. For example, using cURL:

{% tabs %}
{% tab title="cURL" %}
{% code lineNumbers="true" %}

```bash
curl -X POST "https://auth.raalabs.io/oauth2/token" \
  -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
  -d "grant_type=client_credentials"
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
import requests

url = "https://auth.raalabs.io/oauth2/token"
response = requests.post(
    url,
    auth=("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET"),
    data={"grant_type": "client_credentials"},
)
token = response.json()["access_token"]
```

{% endcode %}
{% endtab %}
{% endtabs %}

Replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with the credentials provided to you. This request returns a JSON response containing an **access token** (JWT). The token will look like a long string of characters.

Once you have the token, include it in the **Authorization** header of all API requests:

| Header        | Value                      |
| ------------- | -------------------------- |
| Authorization | Bearer `YOUR_ACCESS_TOKEN` |

For example:\
`Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...`

### Refreshing Access Tokens

Access tokens have a limited lifetime (by default, **1 hour**). The expiration time is encoded within the token. After a token expires, you must request a new one by repeating the Client Credentials grant (i.e. call the `/oauth2/token` endpoint again with your Client ID and Secret). There is no separate "refresh token"; simply obtain a new access token when needed.