Products & Surfaces

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}

Include your key in the Authorization (or X-API-Key) header on every request:

$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 '{"topic": "your input here"}'

The request body is passed directly as the capability’s input: its top-level fields become the capability’s input parameters. For the full request and response contract, including streaming and response formats, see Calling your API endpoints.

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