SCHMA uses Bearer token authentication to secure all external API access. Whether you are querying published articles in a frontend framework or automating schema deployments with CI/CD scripts, your requests must include a valid API key with the appropriate permission scope.

API key types and permission scopes

When generating a key in SCHMA Studio, you select a specific permission scope tailored to your use case:

• Delivery (`delivery`): Restricted strictly to reading published content entries. Delivery keys cannot access draft records, modify entries, or inspect workspace administration settings. They are safe to use in static site generators, edge loaders, and client apps.
• Read Only (`read`): Provides read access to the Management API, including unpublished draft entries, schema structures, and workspace telemetry. Cannot mutate content or models.
• Read & Write (`read_write`): Full administrative access to the Management API. Authorizes creating and editing schemas, publishing entries, modifying assets, and managing workspace webhooks. This scope is required by the SCHMA MCP server.
• Webhook Read (`webhook_read`): Dedicated scope for inspecting webhook delivery logs and verification signatures.

Generating an API key in Studio

To create a new key: open your workspace in SCHMA Studio and navigate to Settings → API Keys. In the Generate Key card:

1. Enter a descriptive label (e.g. Next.js Production Frontend or Cursor MCP Local).
2. Select the required Permissions Scope (delivery, read, or read_write).
3. Choose an Expiration Date (Never expire, 30 days, or 90 days).
4. Click Create API Key.

Required authentication headers

All HTTP requests to SCHMA API endpoints require two standard headers:

curl "https://api.schma.dev/v1/delivery/entries?type=post&limit=10" \
  -H "Authorization: Bearer schma_del_exampletoken123" \
  -H "x-tenant-slug: your-workspace-slug" \
  -H "Content-Type: application/json"

• Authorization: Format as Bearer <your_token>.
• x-tenant-slug: Your workspace slug identifier (found in Settings → General).
• x-environment: (Optional) Target environment, e.g. production or staging (defaults to production).

Token rotation and security practices

To rotate a key without downtime: generate a new key in the Studio, update your application's environment variables (SCHMA_API_KEY), deploy the update, verify that incoming requests succeed, and then click Delete next to the old key in the Studio.