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.

Authorization: Bearer ord_c_XXXXXXXXXXXXXXXX

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

Navigate to Company Settings

Go to the Company Settings page in your Ordinal dashboard.

Open API Keys Section

Click on the “API Keys” tab in the company settings menu.

Create New Key

Click “Create Company API Key” and provide a descriptive name for the key.

Copy Your Key

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

Making Authenticated Requests

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

curl -X GET "https://app.tryordinal.com/api/v1/company/workspaces" \
  -H "Authorization: Bearer ord_c_XXXXXXXXXXXXXXXX"

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

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:

{
  "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

Wrong Key Type

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

{
  "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:

{
  "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:

{
  "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

Use Environment Variables

Store your company API key in environment variables rather than hardcoding it in your application.

export ORDINAL_COMPANY_API_KEY="ord_c_XXXXXXXXXXXXXXXX"

const apiKey = process.env.ORDINAL_COMPANY_API_KEY;

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.

// 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);

Rotate Keys Regularly

Periodically rotate your company API keys to minimize the impact of potential key exposure.

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:

Navigate to company settings
Find the key you want to revoke
Click the ... button and select “Revoke”
Confirm the action