> ## 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 Agency API requests with company API keys

## Overview

The Agency API uses Bearer token authentication with company-scoped API keys. All API requests must include a valid company API key in the `Authorization` header.

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

> [!NOTE]
>
> **Company-Level Authentication**
>
> Company API keys provide access to all workspaces within your company. This is different from workspace API keys, which only provide access to a single workspace.

## Key Differences from Workspace API Keys

| Feature | Company API Key | Workspace API Key |
| - | - | - |
| **Prefix** | `ord_c_*` | `ord_*` |
| **Scope** | All workspaces in company | Single workspace |
| **Can create workspaces** | Yes | No |
| **Can manage workspace API keys** | Yes | No |
| **Can access posts/profiles** | No | Yes |

## Generating a Company API Key

> [!NOTE]
>
> **Enterprise Plan Required**
>
> Company API keys are available on the Enterprise plan. [Contact sales](mailto:sales@tryordinal.com) to upgrade your account.

**1. Navigate to Company Settings**

Go to the Company Settings page in your Ordinal dashboard.

**2. Open API Keys Section**

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

**3. Create New Key**

Click "Create Company 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 company API key securely. It provides access to all workspaces in your company. Never expose it in client-side code, public repositories, or share it with unauthorized users.

## Making Authenticated Requests

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

```bash cURL theme={null}
curl -X GET "https://app.tryordinal.com/api/v1/company/workspaces" \
  -H "Authorization: Bearer ord_c_XXXXXXXXXXXXXXXX"
```

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

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

response = requests.get(
    'https://app.tryordinal.com/api/v1/company/workspaces',
    headers={'Authorization': 'Bearer ord_c_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`

### Wrong Key Type

If you use a workspace API key instead of a company API key:

```json theme={null}
{
  "code": "FORBIDDEN",
  "message": "This endpoint requires a company API key. Use a company-scoped API key to access company-level resources."
}
```

**Status Code:** `403 Forbidden`

### Revoked Key

If the company API key has been revoked:

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

**Status Code:** `403 Forbidden`

### Rate Limited

If you've exceeded the rate limit for your API key:

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

## Error Code Reference

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

## Best Practices

> [accordion] Use Environment Variables
>
> Store your company API key in environment variables rather than hardcoding it in your application.
>
> ```bash theme={null}
> export ORDINAL_COMPANY_API_KEY="ord_c_XXXXXXXXXXXXXXXX"
> ```
>
> ```javascript theme={null}
> const apiKey = process.env.ORDINAL_COMPANY_API_KEY;
> ```

> [accordion] Use Workspace Keys for Workspace Operations
>
> Company API keys cannot access workspace-specific resources like posts and profiles. Use the Agency API to create workspace API keys, then use those keys with the Workspace API.
>
> ```javascript theme={null}
> // 1. Create a workspace API key using your company key
> const { key: workspaceKey } = await createWorkspaceApiKey(companyKey, workspaceId);
>
> // 2. Use the workspace key for post operations
> const posts = await listPosts(workspaceKey);
> ```

> [accordion] Rotate Keys Regularly
>
> Periodically rotate your company API keys to minimize the impact of potential key exposure.

> [accordion] Revoke Compromised Keys
>
> If you suspect a company API key has been compromised, revoke it immediately and generate a new one. Remember that this affects all workspaces in your company.

## Managing Company API Keys

### Viewing Keys

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

* Name and description
* Creation date
* Last used timestamp

### Revoking Keys

To revoke a company API key:

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

> [!WARNING]
>
> Revoking a company API key is permanent and cannot be undone. Any applications using the revoked key will immediately lose access to all company-level operations.


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