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

# API Authentication: Keys, Headers, and Rate Limits

> Trident's REST API uses HTTP Basic authentication with your project Public Key and Secret Key. Learn how to construct and pass your credentials.

Every request to the Trident REST API is authenticated with HTTP Basic auth. You combine your project's **Public Key** and **Secret Key** into a single credential, Base64-encode it, and pass it in the `Authorization` header. All endpoints under `/api/public/trident/` require this header unless otherwise noted.

## Find your API Keys

<Steps>
  <Step title="Open the Trident Dashboard">
    Navigate to [app.usetrident.dev](https://app.usetrident.dev) and sign in.
  </Step>

  <Step title="Go to Project Settings">
    Click your project name in the top navigation, then select **Project Settings**.
  </Step>

  <Step title="Open the API Keys tab">
    Select **API Keys**. You will see your **Public Key** (safe to share with internal services) and your **Secret Key** (treat this like a password).
  </Step>
</Steps>

## Construct the Authorization header

Combine your keys with a colon separator — `publicKey:secretKey` — then Base64-encode the result. Set the encoded string as the value of the `Authorization: Basic` header on every request.

**Base URL:** `https://app.usetrident.dev`

<CodeGroup>
  ```bash curl theme={null}
  # Replace <PUBLIC_KEY> and <SECRET_KEY> with your actual values
  CREDENTIALS=$(echo -n "pk_live_abc123:sk_live_xyz789" | base64)

  curl -X GET "https://app.usetrident.dev/api/public/trident/agents" \
    -H "Authorization: Basic $CREDENTIALS" \
    -H "Accept: application/json"
  ```

  ```typescript TypeScript theme={null}
  const publicKey = process.env.TRIDENT_PROJECT_PUBLIC_KEY!;
  const secretKey = process.env.TRIDENT_PROJECT_SECRET_KEY!;

  const encoded = Buffer.from(`${publicKey}:${secretKey}`).toString("base64");

  const response = await fetch(
    "https://app.usetrident.dev/api/public/trident/agents",
    {
      headers: {
        Authorization: `Basic ${encoded}`,
        Accept: "application/json",
      },
    },
  );

  const data = await response.json();
  ```

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

  public_key = os.environ["TRIDENT_PROJECT_PUBLIC_KEY"]
  secret_key = os.environ["TRIDENT_PROJECT_SECRET_KEY"]

  token = base64.b64encode(f"{public_key}:{secret_key}".encode()).decode()

  response = requests.get(
      "https://app.usetrident.dev/api/public/trident/agents",
      headers={
          "Authorization": f"Basic {token}",
          "Accept": "application/json",
      },
  )
  data = response.json()
  ```
</CodeGroup>

## Store keys as environment variables

Never hard-code your keys in source files. Use environment variables and load them at runtime:

| Variable                     | Description                                  |
| ---------------------------- | -------------------------------------------- |
| `TRIDENT_PROJECT_PUBLIC_KEY` | Your project Public Key (prefix `pk_live_…`) |
| `TRIDENT_PROJECT_SECRET_KEY` | Your project Secret Key (prefix `sk_live_…`) |

## Common authentication errors

| HTTP status        | Meaning                                                                  | Resolution                                                |
| ------------------ | ------------------------------------------------------------------------ | --------------------------------------------------------- |
| `401 Unauthorized` | Missing or malformed `Authorization` header, or Base64 encoding is wrong | Verify the header format is `Basic <base64(pub:secret)>`  |
| `401 Unauthorized` | Secret Key is incorrect                                                  | Double-check the key value in Project Settings            |
| `403 Forbidden`    | Public Key does not match any project, or the project has been deleted   | Verify the Public Key and ensure the project still exists |

## Rate limits

The Trident API enforces per-project rate limits on the `public-api` resource. When you exceed the limit, the API returns `429 Too Many Requests`. Implement exponential back-off in your clients and respect the `Retry-After` header when present.

The unauthenticated public demo scan endpoint (`POST /api/public/scan`) has a separate rate limit of **10 requests per minute per source IP**.

<Warning>
  Keep your Secret Key private. If it is ever exposed in a log, repository, or
  error message, rotate it immediately from the **API Keys** tab in Project
  Settings. Rotating invalidates the old key instantly.
</Warning>