> ## Documentation Index
> Fetch the complete documentation index at: https://ordinal.mintlify.site/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
```

> [!NOTE]
>
> **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.

## Generating an API Key

> [!NOTE]
>
> **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.

**1. Navigate to Workspace Settings**

Go to the [API Keys page](https://app.tryordinal.com/settings/integrations/api) in your workspace.

**2. Open API Keys Section**

Click on the "API Keys" tab in the settings menu.

**3. Create New Key**

Click "Create an API Key" and provide a descriptive name for the key.

**4. Copy Your Key**

Copy the generated API key immediately. For security reasons, the full key is only shown once.

> [!WARNING]
>
> Store your API key securely. Never expose it in client-side code, public repositories, or share it with unauthorized users.

## Making Authenticated Requests

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

```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'}
)
```

## 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

> [accordion] 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] Rotate Keys Regularly
>
> Periodically rotate your API keys to minimize the impact of potential key exposure.

> [accordion] Monitor Key Usage
>
> Regularly review your API key usage in the dashboard to detect any unusual activity.

> [accordion] Revoke Compromised Keys
>
> If you suspect an API key has been compromised, revoke it immediately and generate a new one.

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.