Authentication

The Runtype API uses API keys to authenticate requests. Include your API key in the Authorization header of every authenticated request.

Before you begin

Sign in to the Runtype Dashboard. You need a Runtype account to create an API key.

Create an API key

Create an API key in the dashboard by following these steps:

1. On the Settings > API page, click Create New API Key.
2. Enter a descriptive name for the key.
3. Select the permissions that your application needs.
4. Click Create. The dashboard shows the key once.

Use your API key

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

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

Replace YOUR_API_KEY with the Runtype API key that you created.

API key formats

Runtype uses the following API key prefixes:

Permissions

Use permissions to limit what an API key can do. The following table lists common scopes:

To view all available scopes and permission groups, open the API Keys page and create or edit a key. For more information, see Managing API keys.

Use TELEMETRY:WRITE for collectors, containers, continuous integration (CI) jobs, and other instrumented services. This append-only scope grants ingest access without read or management access. Select the Telemetry Ingest permission group to create a key with this scope. For setup instructions, see Reporting telemetry from an external agent.

Agent self-registration (anonymous start)

If your agent needs an API key before a person creates one, use anonymous-start registration. The agent receives a scoped pre-claim key and can bind it to an email address later. For the protocol specification, see the auth.md anonymous-start pattern.

Prefer the CLI

Use the runtype CLI for a non-interactive registration flow without a browser:

$
runtype auth register --email dana@example.com  # Register and send the one-time code.
$
runtype auth verify YOUR_OTP                    # Complete the claim with the code.
$
runtype auth claim dana@example.com             # Resend or change the email address.

Replace YOUR_OTP with the six-digit code from the email.

The runtype CLI stores the resulting credential for subsequent CLI commands. Each command prints JSON with a next field that identifies the next step. Use the HTTP protocol when you cannot install @runtypelabs/cli.

Discovery

Find the registration flow through either of these discovery signals:

• A WWW-Authenticate header on a 401 response identifies the protected-resource metadata URL.
• The agent_auth block in GET /.well-known/oauth-authorization-server lists the registration endpoints. The auth.md specification describes the protocol.

Register anonymously

The registration and claim endpoints are unauthenticated. The claim token authenticates the claim requests.

Send a POST request to /agent/auth to receive a pre-claim API key and claim token:

$
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_live_ key that expires after 24 hours. It includes these scopes:

• FLOWS:READ and FLOWS:WRITE.
• AGENTS:READ and AGENTS:WRITE.
• RECORDS:READ, TOOLS:READ, and ANALYTICS:READ.
• PRODUCTS:READ, PRODUCTS:WRITE, PRODUCTS:CREATE, and PRODUCTS:UPDATE.
• PRODUCTS:SURFACES:READ and PRODUCTS:CAPABILITIES:READ.

It does not include DISPATCH:*, execute scopes, RECORDS:WRITE, or tool execution. It also excludes SECRETS:*, API-key management, integrations, schedules, webhooks, messaging, agent-to-agent (A2A) scopes, and delete permissions.

Claim the registration

To replace the pre-claim key with a full-access key, send the claim token and your email address to /agent/auth/claim:

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

Replace YOUR_CLAIM_TOKEN with the claim_token that registration returns.

This request sends a one-time code to your email address. Complete the claim by sending that code to /agent/auth/claim/complete:

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

Use the same YOUR_CLAIM_TOKEN value and replace YOUR_OTP with the code from the email.

After successful verification, Runtype revokes the pre-claim key and issues a new full-access rt_live_ key bound to your account. That key has the * scope. Runtype revokes the old key instead of upgrading it. The old key cannot gain full privileges.

Agent registration with an identity assertion (ID-JAG)

If your agent has an ID-JAG (Identity Assertion JWT Authorization Grant) from a trusted agent identity provider, register it with one request. Runtype validates the short-lived JWT and issues a full-access key for a new account tied to the verified email. This flow does not use a pre-claim key or an email one-time code.

$
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"
>
  }'

Replace YOUR_ID_JAG_JWT with the JWT from your identity provider.

The assertion must meet these requirements:

• A trusted agent identity provider issues it. Runtype accepts https://auth.workos.bot (WorkOS).
• Its audience is https://api.runtype.com/agent/auth or https://api.runtype.com.
• It contains a verified email claim: email and email_verified: true.
• It contains a jti claim. Runtype accepts each assertion once and rejects assertions older than 10 minutes.

On success, the response includes status: "claimed" and a full-access rt_live_ key. If the email already belongs to a Runtype account, Runtype returns email_already_registered. Sign in to the dashboard and create an API key instead. The identity_assertion and anonymous identity types appear in the agent_auth block of GET /.well-known/oauth-authorization-server.

Rate limits

Plans do not cap the total number of Flow executions. Some plans carry a burst rate, which limits how many Flow executions you can start per second. If your plan has a burst rate and you exceed it, the API returns 429 with a Retry-After header. If your plan has no burst rate, this check does not apply.

Spending controls return 402 instead of 429. For more information, see Rate limits and usage.

When a burst rate applies, execution responses include these headers:

1
RateLimit-Limit: 100
2
RateLimit-Remaining: 99
3
RateLimit-Reset: 60

Error responses

These examples show common authentication and rate-limit errors.

401 Unauthorized

The API returns 401 when a request lacks a valid API key:

1
{
2
  "error": "Unauthorized"
3
}

403 Forbidden

The API returns 403 when an API key lacks a required permission:

1
{
2
  "error": "Insufficient permissions"
3
}

429 Too many requests

The API returns 429 when a request exceeds a burst rate:

1
{
2
  "error": "Rate limit exceeded"
3
}

Best practices

Use these practices to manage your API keys:

$
export RUNTYPE_API_KEY="YOUR_API_KEY"

Next steps

Continue with these developer guides: