Skip to main content

​
Overview

The Ordinal API uses Bearer token authentication. All API requests must include a valid API key in the Authorization header. 
Authorization: Bearer ord_XXXXXXXXXXXXXXXX
Workspace-Level AuthenticationAPI 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

Pro Plan RequiredThe Ordinal API is available on the Pro plan or higher. Upgrade your workspace to access API features.
1

Navigate to Workspace Settings

Go to the API Keys page 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.
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: 
curl -X GET "https://app.tryordinal.com/api/v1/workspace" \
  -H "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: 
{
  "code": "UNAUTHORIZED",
  "message": "Missing bearer token"
}
Status Code: 401 Unauthorized

​
Invalid or Not Found

If the API key is invalid or doesn’t exist: 
{
  "code": "UNAUTHORIZED",
  "message": "Invalid or unauthorized API key"
}
Status Code: 401 Unauthorized

​
Rate Limited

If you’ve exceeded the rate limit for your API key: 
{
  "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: 
{
  "code": "FORBIDDEN",
  "message": "API key was revoked 2 days ago"
}
Status Code: 403 Forbidden

​
Expired Key

If the API key has expired: 
{
  "code": "FORBIDDEN",
  "message": "API key is expired"
}
Status Code: 403 Forbidden

​
Disabled Key

If the API key has been disabled: 
{
  "code": "FORBIDDEN",
  "message": "Invalid or unauthorized API key"
}
Status Code: 403 Forbidden

​
Insufficient Permissions

If the API key doesn’t have the required permissions: 
{
  "code": "FORBIDDEN",
  "message": "Insufficient permissions"
}
Status Code: 403 Forbidden

​
Insufficient Credits

If your account has run out of API credits: 
{
  "code": "FORBIDDEN",
  "message": "Insufficient credits"
}
Status Code: 403 Forbidden

​
Usage Exceeded

If you’ve exceeded your usage quota: 
{
  "code": "FORBIDDEN",
  "message": "Usage exceeded"
}
Status Code: 403 Forbidden

​
Error Code Reference

Error CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid API key
TOO_MANY_REQUESTS429Rate limit exceeded
FORBIDDEN403Key revoked, expired, disabled, or insufficient permissions

​
Best Practices

Store your API key in environment variables rather than hardcoding it in your application.
export ORDINAL_API_KEY="ord_XXXXXXXXXXXXXXXX"

const apiKey = process.env.ORDINAL_API_KEY;
Periodically rotate your API keys to minimize the impact of potential key exposure.
Regularly review your API key usage in the dashboard to detect any unusual activity.
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
Revoking an API key is permanent and cannot be undone. Any applications using the revoked key will immediately lose access.