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. Agents that already carry an identity assertion from a trusted identity provider can skip the claim ceremony entirely — see Agent registration with an identity assertion.

Prefer the CLI

The Runtype CLI wraps this whole protocol in three non-interactive commands (no TTY, no browser) and stores the resulting credential for every other CLI command:

$
runtype auth register --email user@example.com   # register + send the one-time code in one step
$
runtype auth verify 123456                       # complete the claim; stores the full credential
$
runtype auth claim user@example.com              # re-send or change the email for a pending signup

Every command prints JSON with a next field naming the exact follow-up step. Use the raw HTTP protocol below when you cannot install @runtypelabs/cli.

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.

Agent registration with an identity assertion (ID-JAG)

Agents whose runtime holds an ID-JAG (Identity Assertion JWT Authorization Grant, assertion type urn:ietf:params:oauth:token-type:id-jag) from a trusted agent identity provider can register in a single request — no pre-claim key, no email one-time code. The assertion is a short-lived JWT carrying a verified email; Runtype validates it and issues a full-access key bound to a new account for that email.

$
curl -X POST https://api.runtype.com/agent/auth \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "type": "identity_assertion",
>
    "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
>
    "assertion": "YOUR_ID_JAG_JWT",
>
    "requested_credential_type": "api_key"
>
  }'

Requirements for the assertion:

• Issued by a trusted agent identity provider. Currently https://auth.workos.bot (WorkOS).
• Audience set to https://api.runtype.com/agent/auth (or https://api.runtype.com).
• A verified email claim (email plus email_verified: true).
• A jti claim — each assertion is single-use, and assertions older than 10 minutes are rejected.

On success the response includes status: "claimed" and a full-access rt_* key. If the asserted email already belongs to a Runtype account, the request is rejected with email_already_registered; sign in at use.runtype.com and create a key directly instead. The identity_assertion and anonymous identity types are both advertised in the agent_auth block of GET /.well-known/oauth-authorization-server.

Rate limits

Execution limits are based on your plan tier. The Launch 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..."

Next steps