Products & Surfaces

Authenticating with product API keys

When an API Surface requires authentication, send a valid API key with every request.

Choose an authentication header

The Runtype API accepts a product API key in two headers. Send it as a Bearer token in the Authorization header or as a value in the X-API-Key header:

Authorization header
1Authorization: Bearer papi_YOUR_PRODUCT_KEY

Replace papi_YOUR_PRODUCT_KEY with the full API key for your API Surface. Alternatively, send the same key in the X-API-Key header:

X-API-Key header
1X-API-Key: papi_YOUR_PRODUCT_KEY

Use the same papi_YOUR_PRODUCT_KEY value in either header.

Make authenticated requests

To call a capability, send a POST request to an API Surface endpoint. Use this endpoint pattern:

API Surface endpoint
https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/api/YOUR_CAPABILITY_SLUG

Replace YOUR_PRODUCT_ID with the Product ID. Replace YOUR_SURFACE_ID with the API Surface ID. Replace YOUR_CAPABILITY_SLUG with the capability endpoint slug. Find exact endpoint URLs in the Endpoints or Ship tab of your API Surface.

Include the Authorization or X-API-Key header in every request. This example uses the Authorization header to call a capability:

Call a capability
$curl -X POST https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/api/YOUR_CAPABILITY_SLUG \
>  -H "Authorization: Bearer papi_YOUR_PRODUCT_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"topic": "machine learning"}'

Replace papi_YOUR_PRODUCT_KEY with the full API key. Replace the other placeholders with the values for your Product, API Surface, and capability endpoint. The request body passes its top-level fields directly to the capability as input. For the full request and response contract, including streaming and response formats, see Calling your API endpoints.

Use the product API key prefix

API Surface keys use the papi_ prefix. Create and manage API keys on the Keys tab. Find endpoint URLs and integration examples on the Endpoints and Ship tabs.

Handle authentication errors

Check the status code and response body when a request fails authentication. Requests without a recognized API key return 401 Unauthorized. For a request without a key, the response body is:

Missing API key response
1{
2  "error": "Authentication required",
3  "message": "Provide API key via Authorization: Bearer papi_xxx or X-API-Key header"
4}

Invalid or expired keys also return 401 Unauthorized with an error message that identifies the failure.

Requests with a valid key that lacks access to an endpoint return 403 Forbidden. For a capability endpoint, the response body is:

Insufficient capability scope response
1{
2  "error": "Forbidden",
3  "message": "API key does not have access to this endpoint"
4}

A scoped API key that excludes the endpoint triggers this response.

Protect your API keys

Follow these practices to protect your API keys:

  • Store API keys in environment variables instead of source code.
  • Use separate API keys for development and production.
  • Rotate an API key after exposure and on a regular schedule.
  • Scope each API key to the capabilities it needs.

Do not expose API keys in client-side JavaScript, mobile apps, or public repositories. Send requests from server-side code or through a proxy that keeps the key private.

Rotate a compromised API key

To replace a compromised API key, follow these steps:

  1. On the Products page, open the Product that contains the API Surface.
  2. Open the API Surface.
  3. On the Keys tab, find the compromised API key.
  4. Click the delete control for the compromised key.
  5. In the confirmation dialog, click Delete Key.
  6. On the Keys tab, click Generate Key.
  7. Copy the replacement API key.
  8. Update your server-side configuration with the replacement key.

After you delete a key, requests that use it fail authentication.

Next steps

Continue with these guides: