API Keys

Manage API keys for programmatic access to the Orderly API. API keys are scoped to specific permissions and are tied to the organization. Only users with the Admin or Owner role can manage API keys.

List API Keys

GET/api/api-keys

List all API keys for the organization.

Admin or Owner

Returns all API keys for the current organization. The key value itself is only shown once at creation time; subsequent requests show only a masked prefix.


curl -X GET "https://api.orderly.dev/api/api-keys" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response


{
  "data": [
    {
      "id": "uuid",
      "name": "Production Integration",
      "key_prefix": "ord_sk_prod_****",
      "scopes": ["orders:read", "orders:write", "shipments:read"],
      "last_used_at": "2026-01-15T10:30:00Z",
      "expires_at": null,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Create API Key

POST/api/api-keys

Create a new API key with specified scopes.

Admin or Owner

Creates a new API key. The full key value is returned only in the creation response. Store it securely — it cannot be retrieved again.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name for the key
`scopes`	string[]	Yes	Array of permission scopes
`expires_at`	string	No	Expiration date (ISO 8601, or `null` for no expiration)

Available Scopes

Scope	Description
`orders:read`	Read orders
`orders:write`	Create and update orders
`shipments:read`	Read shipments
`shipments:write`	Create and update shipments
`bridges:read`	Read bridges and bridge types
`bridges:write`	Create, update, and delete bridges
`operations:read`	Read operations
`operations:write`	Create operations
`operations:execute`	Execute, cancel, and undo operations
`dispatchers:read`	Read dispatchers and condition sets
`dispatchers:write`	Manage dispatchers and condition sets
`transformations:read`	Read transformations
`transformations:write`	Manage transformations
`carrier-accounts:read`	Read carrier accounts
`carrier-accounts:write`	Manage carrier accounts
`rates:read`	Get shipping rates
`pickups:read`	Read pickups
`pickups:write`	Schedule and cancel pickups
`webhooks:manage`	Manage webhooks
`agent:read`	Read agent conversations
`agent:write`	Interact with the AI agent
`embed:manage`	Manage embed configuration
`insights:read`	Read analytics and insights


curl -X POST "https://api.orderly.dev/api/api-keys" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "scopes": ["orders:read", "orders:write", "shipments:read", "shipments:write"]
  }'

Response


{
  "data": {
    "id": "uuid",
    "name": "Production Integration",
    "key": "ord_sk_prod_a1b2c3d4e5f6...",
    "scopes": ["orders:read", "orders:write", "shipments:read", "shipments:write"],
    "created_at": "2026-01-15T10:30:00Z"
  }
}

Important: Copy the key value immediately. It will not be shown again.

Revoke API Key

DELETE/api/api-keys/:id

Revoke an API key, permanently disabling it.

Admin or Owner

Permanently revokes an API key. Any requests using this key will immediately receive 401 Unauthorized responses.


curl -X DELETE "https://api.orderly.dev/api/api-keys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."