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

# Authentication

> Secure your API requests with Bearer token authentication

## Overview

The Ordinal API uses Bearer token authentication. All API requests must include a valid API key in the `Authorization` header.

```bash theme={null}
Authorization: Bearer ord_XXXXXXXXXXXXXXXX
```

<Info>
  **Workspace-Level Authentication**

  API keys are scoped to a specific workspace and provide access to all resources within that workspace. If you're an agency managing multiple client workspaces, you'll need to create a separate API key for each workspace.
</Info>

## Generating an API Key

<Info>
  **Pro Plan Required**

  The Ordinal API is available on the Pro plan or higher. [Upgrade your workspace](https://app.tryordinal.com/settings/pricing) to access API features.
</Info>

<Steps>
  <Step title="Navigate to Workspace Settings">
    Go to the [API Keys page](https://app.tryordinal.com/settings/integrations/api) in your workspace.
  </Step>

  <Step title="Open API Keys Section">
    Click on the "API Keys" tab in the settings menu.
  </Step>

  <Step title="Create New Key">
    Click "Create an API Key" and provide a descriptive name for the key.
  </Step>

  <Step title="Copy Your Key">
    Copy the generated API key immediately. For security reasons, the full key is only shown once.
  </Step>
</Steps>

<Warning>
  Store your API key securely. Never expose it in client-side code, public repositories, or share it with unauthorized users.
</Warning>

## Making Authenticated Requests

Include your API key in the `Authorization` header with the `Bearer` prefix:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.tryordinal.com/api/v1/workspace" \
    -H "Authorization: Bearer ord_XXXXXXXXXXXXXXXX"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.tryordinal.com/api/v1/workspace', {
    headers: {
      'Authorization': 'Bearer ord_XXXXXXXXXXXXXXXX'
    }
  });
  ```

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

  response = requests.get(
      'https://app.tryordinal.com/api/v1/workspace',
      headers={'Authorization': 'Bearer ord_XXXXXXXXXXXXXXXX'}
  )
  ```
</CodeGroup>

## Authentication Errors

When authentication fails, the API returns specific error codes to help you diagnose the issue.

### Missing Token

If no authorization header is provided:

```json theme={null}
{
  "code": "UNAUTHORIZED",
  "message": "Missing bearer token"
}
```

**Status Code:** `401 Unauthorized`

### Invalid or Not Found

If the API key is invalid or doesn't exist:

```json theme={null}
{
  "code": "UNAUTHORIZED",
  "message": "Invalid or unauthorized API key"
}
```

**Status Code:** `401 Unauthorized`

### Rate Limited

If you've exceeded the rate limit for your workspace:

```json theme={null}
{
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit of 100 requests per 60s exceeded. Quota resets in 45 seconds"
}
```

**Status Code:** `429 Too Many Requests`

### Revoked Key

If the API key has been revoked:

```json theme={null}
{
  "code": "FORBIDDEN",
  "message": "API key was revoked 2 days ago"
}
```

**Status Code:** `403 Forbidden`

### Expired Key

If the API key has expired:

```json theme={null}
{
  "code": "FORBIDDEN",
  "message": "API key is expired"
}
```

**Status Code:** `403 Forbidden`

### Disabled Key

If the API key has been disabled:

```json theme={null}
{
  "code": "FORBIDDEN",
  "message": "Invalid or unauthorized API key"
}
```

**Status Code:** `403 Forbidden`

### Insufficient Permissions

If the API key doesn't have the required permissions:

```json theme={null}
{
  "code": "FORBIDDEN",
  "message": "Insufficient permissions"
}
```

**Status Code:** `403 Forbidden`

### Insufficient Credits

If your account has run out of API credits:

```json theme={null}
{
  "code": "FORBIDDEN",
  "message": "Insufficient credits"
}
```

**Status Code:** `403 Forbidden`

### Usage Exceeded

If you've exceeded your usage quota:

```json theme={null}
{
  "code": "FORBIDDEN",
  "message": "Usage exceeded"
}
```

**Status Code:** `403 Forbidden`

## Error Code Reference

| Error Code          | HTTP Status | Description                                                 |
| ------------------- | ----------- | ----------------------------------------------------------- |
| `UNAUTHORIZED`      | 401         | Missing or invalid API key                                  |
| `TOO_MANY_REQUESTS` | 429         | Rate limit exceeded                                         |
| `FORBIDDEN`         | 403         | Key revoked, expired, disabled, or insufficient permissions |

## Best Practices

<AccordionGroup>
  <Accordion title="Use Environment Variables">
    Store your API key in environment variables rather than hardcoding it in your application.

    ```bash theme={null}
    export ORDINAL_API_KEY="ord_XXXXXXXXXXXXXXXX"
    ```

    ```javascript theme={null}
    const apiKey = process.env.ORDINAL_API_KEY;
    ```
  </Accordion>

  <Accordion title="Rotate Keys Regularly">
    Periodically rotate your API keys to minimize the impact of potential key exposure.
  </Accordion>

  <Accordion title="Monitor Key Usage">
    Regularly review your API key usage in the dashboard to detect any unusual activity.
  </Accordion>

  <Accordion title="Revoke Compromised Keys">
    If you suspect an API key has been compromised, revoke it immediately and generate a new one.
  </Accordion>
</AccordionGroup>

## Managing API Keys

### Viewing Keys

You can view all your API keys in the workspace settings. Each key shows:

* Name and description
* Creation date
* Last used timestamp

### Revoking Keys

To revoke an API key:

1. Navigate to workspace settings
2. Find the key you want to revoke
3. Click the `...` button and select "Revoke"
4. Confirm the action

<Warning>
  Revoking an API key is permanent and cannot be undone. Any applications using the revoked key will immediately lose access.
</Warning>