Authentication

The Runtype API uses API keys for authentication. Include your API key in the Authorization header of every request.

Getting an API Key

1. Log in to your Runtype Dashboard
2. Go to Settings > API
3. Click Create New Key
4. Give your key a descriptive name
5. Select the permissions you need
6. Copy your key - it won’t be shown again!

Using Your API Key

Include the API key in the Authorization header with the Bearer scheme:

$
curl https://api.runtype.com/v1/flows \
>
  -H "Authorization: Bearer rt_live_abc123..."

API Key Formats

Permissions

API keys can be scoped to specific permissions. Common scopes include:

When you create or edit a key on the dashboard’s API Keys page (see Managing API keys), you’ll see the complete list of available scopes along with pre-built permission groups for common use cases.

Agent self-registration (anonymous start)

An AI agent can obtain a scoped Runtype API key on its own, without a human creating one first, and later bind that key to a real user. This follows the auth.md anonymous-start pattern, so agents that understand the standard can discover and complete the flow automatically.

Discovery

An agent finds the flow in two ways:

• A WWW-Authenticate header on 401 responses points to the discovery document.
• The agent_auth block in GET /.well-known/oauth-authorization-server describes the endpoints, and runtype.com/auth.md documents them in prose.

Step 1 — register

POST /agent/auth returns a pre-claim API key plus a claim token. No human is involved.

$
curl -X POST https://api.runtype.com/agent/auth \
>
  -H "Content-Type: application/json" \
>
  -d '{ "type": "anonymous", "requested_credential_type": "api_key" }'

The pre-claim key is an rt_* key that expires after 24 hours. It grants broad platform access for building and running — dispatch, flows, agents, records, reading and executing tools, and products — but excludes sensitive and destructive operations: no secrets, API keys, integrations, schedules, webhooks, messaging, or A2A scopes, and no delete permissions.

Step 2 — claim (bind to a user)

To upgrade the key to full access, claim it against a real email address:

$
curl -X POST https://api.runtype.com/agent/auth/claim \
>
  -H "Content-Type: application/json" \
>
  -d '{ "claim_token": "YOUR_CLAIM_TOKEN", "email": "user@example.com" }'

This emails a one-time code to the address. Complete the claim with that code:

$
curl -X POST https://api.runtype.com/agent/auth/claim/complete \
>
  -H "Content-Type: application/json" \
>
  -d '{ "claim_token": "YOUR_CLAIM_TOKEN", "otp": "123456" }'

On success, Runtype revokes the pre-claim key and issues a fresh, full-access key bound to the user. Issuing a new key rather than upgrading in place prevents any copy of the old key from silently gaining full privileges.

Rate limits

Execution limits are based on your plan tier. The Build tier includes 50 full-speed executions per day, after which slow mode activates. Paid plans have higher burst limits and monthly execution pools.

For full details on plan-specific limits, see Rate limits and usage.

Rate limit and quota headers are included in responses:

RateLimit-Limit: 100
RateLimit-Remaining: 99
RateLimit-Reset: 60

Error Responses

401 Unauthorized

1
{
2
  "error": "Unauthorized",
3
  "details": "Invalid or missing API key"
4
}

403 Forbidden

1
{
2
  "error": "Forbidden",
3
  "details": "Missing required permission: FLOWS:WRITE"
4
}

429 Too Many Requests

1
{
2
  "error": "Rate limit exceeded",
3
  "details": "Execution limit reached for your current plan"
4
}

Best Practices

$
export RUNTYPE_API_KEY="rt_live_abc123..."