Products & Surfaces

Scoping API keys to capabilities

Limit API keys to specific capabilities for better security and access control. Scoped keys can only invoke the capabilities you explicitly allow.

Why scope API keys

Scoping provides security and organizational benefits:

  • Least privilege — Give third parties access to only what they need
  • Reduce attack surface — Compromised keys can’t access all capabilities
  • Usage tracking — See which keys are calling which capabilities
  • Billing isolation — Track costs per integration or customer

Creating a scoped key

Capability scoping is currently configured through the API rather than the dashboard key dialog (the Generate API Key dialog only sets a name and key type). Create a key with a scopes array listing the Capability names it may invoke:

$curl -X POST https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/keys \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "Mobile app - FAQ only",
>    "scopes": ["FAQ"]
>  }'

Copy the returned key value immediately — it is shown only once. A key created without a scopes array is unscoped and can invoke every Capability on the Product.

Access denied errors

When a key tries to access a capability it’s not scoped to:

1{
2  "error": "Forbidden",
3  "message": "API key does not have access to capability 'My Capability'"
4}

HTTP status: 403 Forbidden

Changing a key’s scope

A key’s scope is set when the key is created and cannot be edited — there is no update endpoint or edit UI for surface keys. To change which Capabilities a key can access, delete the key and create a new one with the desired scopes.

Use cases

Customer-specific keys

Create a key for each customer, scoped to capabilities relevant to them:

  • Customer A: FAQ + Order lookup capabilities
  • Customer B: FAQ capability only

Integration separation

Isolate different integrations:

  • Mobile app key: All capabilities
  • Public API key: Safe, rate-limited capabilities only
  • Internal tools key: Admin and diagnostic capabilities

Third-party developers

Give partners access to specific features without exposing your entire Product.

Name keys descriptively with their scope (e.g., “Acme Corp - FAQ only” instead of “API Key 3”). This makes management easier as you scale.

Unscoped keys

Keys can also be unscoped, granting access to all capabilities on the Product. This is convenient for trusted integrations but increases risk if the key is compromised.

Use unscoped keys only when necessary and rotate them regularly.

Next steps