API Keys

API keys provide long-lived, programmatic access to the arg.ai API. They are scoped to an organization and authenticate either as your user account or as a service account. You can create and manage API keys from the dashboard at arg.ai/platform/api-keys, or programmatically using the endpoints below.

Service accounts

Service accounts are identity containers for API keys. They represent non-human actors (CI/CD pipelines, scripts, integrations) that need to interact with the API.

Create a service account

curl -X POST https://api.arg.ai/api/service-accounts \
  -H "X-API-Key: arg_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_123",
    "name": "CI Pipeline"
  }'

You can also use Authorization: Bearer YOUR_ACCESS_TOKEN. API-key callers must have service_account:create, and the caller must outrank the role assigned to the new service account.

List service accounts

curl "https://api.arg.ai/api/service-accounts?organization_id=org_123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Each API key is tied to an organization. User-owned keys inherit your current access within that organization. Service-account keys inherit the selected service account’s organization role and workspace/file grants. API key management endpoints accept either a user access token or an API key:

# User session
Authorization: Bearer YOUR_ACCESS_TOKEN

# Service account API key
X-API-Key: arg_live_abc123...

When you use an API key to manage API keys, the key principal must have the matching API key permission. API-key callers must create service-account keys; user-owned keys are created from a user session.

Create an API key

curl -X POST https://api.arg.ai/api/keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_123",
    "name": "Personal Automation Key"
  }'

Include service_account_id to create a service-account key:

curl -X POST https://api.arg.ai/api/keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_123",
    "name": "Production Key",
    "service_account_id": "sa_456"
  }'

You can also use X-API-Key instead of Authorization if the key has api_key:create; API-key callers must provide service_account_id. The response includes the full API key string — store it securely, as it cannot be retrieved again:

{
  "api_key": "arg_live_abc123...",
  "key": {
    "id": "key_789",
    "name": "Production Key",
    "key_prefix": "arg_live_abc",
    "principal_type": "service_account",
    "service_account_id": "sa_456",
    "is_active": true,
    "created_at": "2025-01-01T00:00:00Z"
  }
}

For user-owned keys, principal_type is "user" and service_account_id is null.

Using API keys

Include the key in the X-API-Key header:

curl https://api.arg.ai/api/workspaces \
  -H "X-API-Key: arg_live_abc123..."

Revoking and deleting keys

Revoke a key to disable it without deleting:

curl -X POST "https://api.arg.ai/api/keys/key_789/revoke?organization_id=org_123" \
  -H "X-API-Key: arg_live_abc123..."

Delete a key permanently:

curl -X DELETE "https://api.arg.ai/api/keys/key_789?organization_id=org_123" \
  -H "X-API-Key: arg_live_abc123..."

Permissions

API key management is controlled by organization role permissions:

Permission	Allows
`api_key:view`	List API keys
`api_key:create`	Create API keys
`api_key:revoke`	Revoke API keys
`api_key:delete`	Permanently delete API keys
`api_key:*`	All API key management actions

Organization admins and owners include API key management by default. Custom roles can grant the granular permissions above. Creating service accounts accepts either a user session or an API key with service_account:create. Listing service accounts, changing service account roles, and deleting service accounts still require a user session with the matching service_account:* permission. API keys inherit access from their user or service-account principal. API key management calls require api_key:view, api_key:create, api_key:revoke, or api_key:delete; service-account creation requires service_account:create.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

API Keys

Service accounts

Create a service account

List service accounts

API keys

Create an API key

Using API keys

Revoking and deleting keys

Permissions

​Service accounts

​Create a service account

​List service accounts

​API keys

​Create an API key

​Using API keys

​Revoking and deleting keys

​Permissions

Service accounts

Create a service account

List service accounts

API keys

Create an API key

Using API keys

Revoking and deleting keys

Permissions