> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate with the Toktra API using OAuth 2.0 or API keys.

The Toktra API supports two authentication methods: **OAuth 2.0 client credentials** for applications that need scoped, short-lived access, and **API keys** for simpler server-to-server integrations.

## OAuth 2.0

OAuth 2.0 with the `client_credentials` grant is the recommended method. It issues short-lived tokens that expire automatically, reducing the blast radius if a token is ever leaked.

<Steps>
  <Step title="Create an OAuth client">
    In the Toktra dashboard, go to **Developer → OAuth Clients** and click **New client**. Give it a descriptive name (e.g., `ci-pipeline` or `data-export-service`) and save. You will receive a `client_id` and `client_secret` — copy the secret now, as it will not be shown again.
  </Step>

  <Step title="Exchange credentials for an access token">
    POST to `/v1/oauth/token` with `grant_type=client_credentials` and your client credentials in the request body.

    ```bash theme={null}
    curl -X POST https://api.toktra.io/v1/oauth/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
    ```

    The response contains your access token:

    ```json theme={null}
    {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "token_type": "bearer",
      "expires_in": 3600
    }
    ```
  </Step>

  <Step title="Use the token">
    Include the token in the `Authorization` header on every API request:

    ```bash theme={null}
    curl https://api.toktra.io/v1/usage \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```
  </Step>
</Steps>

### Token expiry

Access tokens expire after **3,600 seconds (1 hour)** by default. When a token expires, the API returns `401 Unauthorized` with `"error": "unauthorized"`. Your application should request a new token and retry the request.

<Tip>
  Implement proactive token refresh by caching the token and requesting a new one a minute or two before `expires_in` elapses, rather than waiting for a 401.
</Tip>

### Managing OAuth clients

You can create, list, and revoke OAuth clients programmatically via the `/v1/oauth/clients` endpoints.

<CodeGroup>
  ```bash List clients theme={null}
  curl https://api.toktra.io/v1/oauth/clients \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```bash Revoke a client theme={null}
  curl -X DELETE https://api.toktra.io/v1/oauth/clients/CLIENT_ID \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

***

## API keys

API keys are long-lived credentials suited for simple server-to-server integrations where managing token refresh is unnecessary.

To create an API key, go to **Developer → API Keys** in the Toktra dashboard and click **New API key**. Copy the key immediately — it is shown only once.

Pass the API key directly as a Bearer token:

```bash theme={null}
curl https://api.toktra.io/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Warning>
  API keys do not expire automatically. Treat them like passwords — store them in a secrets manager and never commit them to source control.
</Warning>

***

## Security best practices

* **One client per integration.** Create a separate OAuth client or API key for each service or pipeline. This way you can revoke access to a single integration without affecting others.
* **Rotate regularly.** Rotate API keys and OAuth client secrets on a regular schedule (e.g., every 90 days) and immediately after any suspected exposure.
* **Use environment variables.** Never hardcode credentials. Store them in environment variables or a secrets manager such as AWS Secrets Manager or HashiCorp Vault.
* **Prefer OAuth for user-facing apps.** OAuth tokens expire automatically and are easier to scope than long-lived API keys.