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

# Authentication

> Authenticate your API requests with API keys

All Trackly SMS API requests require authentication using an API key. API keys are scoped to your account and can be created and managed from the dashboard.

API keys follow the format `trk_[32-char-alphanumeric]` (e.g., `trk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6`).

A key created with `sandbox: true` is a sandbox (test) key. Requests authenticated with a sandbox key are simulated — nothing is delivered and nothing is billed. Toggle this when creating the key from **Settings > API Keys** or by passing `"sandbox": true` in the create-key request body.

## Getting Your API Key

<Steps>
  <Step title="Navigate to API Keys">
    Log into the [Trackly SMS Dashboard](https://app.tracklysms.com) and go to **Settings > API Keys**
  </Step>

  <Step title="Create a New Key">
    Click **Create API Key** and give it a descriptive name (e.g., "Production API", "Development")
  </Step>

  <Step title="Copy Your Key">
    Copy the API key immediately - it won't be shown again
  </Step>
</Steps>

<Warning>
  Keep your API keys secure. Never commit them to version control or expose them in client-side code.
</Warning>

## Using Your API Key

Include your API key in the `X-Api-Key` header with every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.tracklysms.com/api/v2/send \
    -H "X-Api-Key: trk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{"to": "+14155551234", "body": "Hello!", "list_number": "+18005551234"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tracklysms.com/api/v2/send",
      headers={
          "X-Api-Key": "trk_your_api_key_here",
          "Content-Type": "application/json"
      },
      json={
          "to": "+14155551234",
          "body": "Hello!",
          "list_number": "+18005551234"
      }
  )
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.tracklysms.com/api/v2/send", {
    method: "POST",
    headers: {
      "X-Api-Key": "trk_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: "+14155551234",
      body: "Hello!",
      list_number: "+18005551234",
    }),
  });
  ```
</CodeGroup>

<Info>
  As an alternative, you can pass the same key in an `Authorization: Bearer <key>` header (e.g. `Authorization: Bearer trk_your_api_key_here`). If both `X-Api-Key` and `Authorization: Bearer` are present, `X-Api-Key` takes precedence. `X-Api-Key` remains the recommended header.
</Info>

## Authentication Errors

If authentication fails, you'll receive a `401 Unauthorized` or `403 Forbidden` response:

<Tabs>
  <Tab title="Missing API Key">
    ```json theme={null}
    {
      "error": "Invalid credentials",
      "code": "invalid_credentials"
    }
    ```

    HTTP `401`
  </Tab>

  <Tab title="Invalid API Key">
    ```json theme={null}
    {
      "error": "Invalid credentials",
      "code": "invalid_credentials"
    }
    ```

    HTTP `401`
  </Tab>

  <Tab title="Account Suspended">
    ```json theme={null}
    {
      "error": "Account is suspended",
      "code": "account_suspended"
    }
    ```

    HTTP `403`. Returned when a valid API key's owning account has been suspended by Trackly. The API key itself is still technically valid, but all requests are rejected until the account is reinstated. Contact `support@tracklysms.com`.
  </Tab>
</Tabs>

<Info>
  Account suspension is enforced at request time, not at API key creation time. A suspended account whose API keys were active before suspension will start receiving `403 Account is suspended` on every call immediately after the admin action, without waiting for any cache or token to expire.
</Info>

## Product Access Errors

Some endpoints are gated by per-account product entitlements. If your account isn't enabled for a given product, requests to that product's endpoints return `403 Forbidden` with a `{product}_not_enabled` code:

```json theme={null}
{
  "error": "EMAIL product not enabled for this account",
  "code": "email_not_enabled"
}
```

The `code` follows the pattern `{product}_not_enabled` (e.g. `email_not_enabled`, `partnerships_not_enabled`). To enable a product on your account, contact `support@tracklysms.com`. SMS sending endpoints are enabled for all active accounts by default and do not return this error.

## API Key Best Practices

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="leaf">
    Store API keys in environment variables, not in code
  </Card>

  <Card title="Rotate Regularly" icon="arrows-rotate">
    Create new keys periodically and revoke old ones
  </Card>

  <Card title="Separate Environments" icon="code-branch">
    Use different keys for development and production
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Check the "Last Used" timestamp to detect unauthorized use
  </Card>
</CardGroup>

## Managing API Keys

From the API Keys page in the dashboard, you can:

| Action     | Description                                          |
| ---------- | ---------------------------------------------------- |
| **Create** | Generate a new API key with a custom name            |
| **View**   | See key name, creation date, and last used timestamp |
| **Delete** | Permanently revoke a key (cannot be undone)          |

<Info>
  Deleting an API key immediately invalidates it. Any requests using that key will fail with a `401` error.
</Info>

## Linking Discord with API Keys

If you use our Discord integration, you can link your Discord account to your Trackly account using an API key:

```
/sms link your_api_key_here
```

This allows you to:

* View usage and balance from Discord
* Create and manage support tickets
* Receive real-time alerts

See [Discord Integration](/integrations/discord) for details.

## Next Steps

<CardGroup cols={2}>
  <Card title="V2 API Overview" icon="book" href="/api-reference/v2/overview">
    Explore all v2 endpoints
  </Card>

  <Card title="Send First SMS" icon="paper-plane" href="/quickstarts/send-first-sms">
    Send your first message
  </Card>
</CardGroup>