Authenticating with product API keys

API surfaces use API keys for authentication. Include your key in the Authorization header of every request.

Authentication method

Runtype uses Bearer token authentication. Include your API key in the Authorization header or the X-API-Key header:

$
Authorization: Bearer YOUR_API_KEY

$
X-API-Key: YOUR_API_KEY

Making authenticated requests

API Surface endpoints follow this pattern:

https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/{capabilitySlug}

Example using curl:

$
curl -X POST https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/{capabilitySlug} \
>
  -H "Authorization: Bearer papi_xxxxxx" \
>
  -H "Content-Type: application/json" \
>
  -d '{"input": "Your input here"}'

Example using JavaScript fetch:

1
const response = await fetch('https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/{capabilitySlug}', {
2
  method: 'POST',
3
  headers: {
4
    'Authorization': 'Bearer papi_xxxxxx',
5
    'Content-Type': 'application/json'
6
  },
7
  body: JSON.stringify({ input: 'Your input here' })
8
});
9
10
const data = await response.json();

Example using Python:

1
import requests
2
3
response = requests.post(
4
    'https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/{capabilitySlug}',
5
    headers={
6
        'Authorization': 'Bearer papi_xxxxxx',
7
        'Content-Type': 'application/json'
8
    },
9
    json={'input': 'Your input here'}
10
)
11
12
data = response.json()

API key prefixes

API Surface keys use the papi_ prefix. Find your exact endpoint URLs and keys in the Endpoints and Keys tabs of your API Surface.

Authentication errors

Common authentication error responses:

401 Unauthorized:

1
{
2
  "error": "Invalid or missing API key"
3
}

Causes: Missing Authorization header, incorrect key format, or revoked key

403 Forbidden:

1
{
2
  "error": "API key does not have permission to access this resource"
3
}

Causes: Key scoped to different capabilities, or insufficient permissions

Best practices

• Environment variables — Store keys in env vars, never in code
• Separate keys — Use different keys for dev and production
• Rotate regularly — Generate new keys periodically and revoke old ones
• Scope permissions — Limit keys to only the capabilities they need

Never expose API keys in client-side JavaScript, mobile apps, or public repositories. Use server-side code or secure proxy services.

Rotating compromised keys

If a key is exposed:

1. Go to your API surface settings
2. Find the compromised key
3. Click Revoke
4. Create a new key
5. Update your application with the new key

Revoked keys stop working immediately.

Next steps

• Calling your API endpoints for request/response details
• Scoping API keys to capabilities
• Setting up an API surface