Troubleshooting5 min read·Updated October 2026

Resolving API 401 and 403 errors

An actionable diagnostic guide to distinguish and fix HTTP 401 Unauthorized and 403 Forbidden responses, permission scopes, and token headers.

Before you begin

An API key generated in SCHMA Studio
A client application or HTTP client (cURL, Postman, Fetch) receiving 401 or 403 responses

When integrating with SCHMA APIs or the @schmadev/client SDK, encountering a 401 Unauthorized or 403 Forbidden status code can halt data fetching. While both represent access denial, they indicate fundamentally different issues in the authentication and authorization chain.

The difference between 401 and 403 errors

Status Code	Meaning	Root Cause	Resolution
`401 Unauthorized`	Authentication failure	Missing, expired, revoked, or malformed API token, or missing `x-tenant-slug` header.	Check Bearer formatting, regenerate the key, and verify the workspace slug.
`403 Forbidden`	Authorization failure	Valid token, but lacks the necessary permission scope for the requested operation.	Upgrade key scope from `delivery` to `read` or `read_write`, or verify plan limits.

Troubleshooting 401 Unauthorized

A 401 status indicates that the SCHMA API Gateway could not authenticate the caller. Check the following items:

Header Syntax: Ensure the header is exactly Authorization: Bearer <token>. Double-check for missing spaces, accidental quotation marks, or double prefixes like Bearer Bearer ....
Workspace Slug Header: Verify that x-tenant-slug is included in the request headers and exactly matches your target workspace slug in the Studio.
Key Deletion or Revocation: Log into the Studio under Settings → API Keys and confirm that the key has not been deleted or revoked.
Environment Variables: If querying from Next.js or Node.js, ensure process.env.SCHMA_API_KEY is loaded and not returning undefined.

Troubleshooting 403 Forbidden

A 403 status indicates that your token was successfully recognized, but the key lacks permission to perform the requested endpoint action. The API response usually includes the error code INSUFFICIENT_API_KEY_SCOPE.

Using a Delivery Key for Management Operations: Delivery keys (delivery scope) can ONLY read published content. If you try to query drafts, inspect schemas, or create entries using a delivery key, the API returns a 403 error.
Using a Read Key for Mutations: A key with read scope can inspect drafts and schemas, but cannot mutate content (POST, PUT, DELETE). Mutations require a key with read_write scope.
Plan Feature Gates: Certain API endpoints (such as AI generation runs or advanced MCP tools) require a Pro or Max workspace plan.

Isolating credential issues with cURL

To rule out framework middleware or SDK configuration bugs, make a raw HTTP request directly from your command line:

cURL Authentication Test

curl -v "https://api.schma.dev/v1/delivery/entries?type=post&limit=1" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "x-tenant-slug: your_workspace_slug_here"

Review the verbose HTTP headers in the response. If the response returns HTTP/2 200, your credentials and headers are correct. If it returns 401 or 403, inspect the JSON error body for the exact reason.

Recovering from expired or revoked tokens

If a token has expired (30-day or 90-day expiration policy) or was revoked: navigate to Settings → API Keys, generate a new token with Never expire, copy the raw token, update your hosting provider's environment variables, and trigger a redeploy.