Authentication

The Workspace API uses API keys for authentication. Each key is scoped to a single workspace and has a specific permission level.

API Keys

Creating an API Key

1. Open your workspace in the Admin app
2. Navigate to workspace settings
3. Create a new API key
4. Choose a permission level:
   • Read & Write — full CRUD access
   • Read Only — only GET requests are allowed
5. Optionally set an expiration date
6. Copy the key immediately — it's only shown once

WARNING

API keys are shown only once when created or rotated. Store them securely. If you lose a key, you can rotate it to get a new one.

Using an API Key

Include the key in the Authorization header as a Bearer token:

GET /api/v1/acme-corp/sales/Customer
Authorization: Bearer sk_live_abc123...

Permission Levels

Permission	GET	POST	PUT	DELETE
Read & Write	Yes	Yes	Yes	Yes
Read Only	Yes	No	No	No

Attempting a write operation with a read-only key returns 403 Forbidden.

Key Expiration

API keys can have an optional expiration date. Expired keys return 401 Unauthorized. Create a new key before the current one expires to avoid downtime.

Workspace Scoping

Each API key is bound to a specific organization and workspace. A key for acme-corp/sales cannot access data in acme-corp/inventory. Attempting to use a key outside its workspace returns 401 Unauthorized.

Security

Key Storage

API keys are SHA-256 hashed before storage. SchemaStack never stores your raw key — only the hash is persisted. This means:

• If the database is compromised, attackers cannot recover your keys
• Lost keys cannot be retrieved — rotate the key to generate a new secret
• The keyPrefix (first 8 characters) is stored separately for identification in the admin UI

Expiration & Rotation

• Expiration: Set an optional expiration date when creating a key. Expired keys immediately return 401 Unauthorized.
• Rotation: Use the rotate action to generate a new secret while keeping the key's name, permissions, and expiration. The old secret stops working immediately and the new key is returned once — store it securely. Revoked keys cannot be rotated.
• Revocation: Revoked keys stop working immediately.

Auditing

The last_used_at timestamp is updated on each request, allowing you to identify unused keys that should be revoked.

Best Practices

• Use Read Only keys whenever write access isn't needed
• Set expiration dates — keys without expiration are a security risk
• Rotate regularly — replace keys periodically even if not compromised
• Revoke immediately if a key may be compromised
• One key per integration — create separate keys for each external service (Jotform, Zapier, Make) so you can revoke them independently

External Identity Providers

You can configure an external OIDC identity provider (Auth0, Clerk, Firebase) so your end-users can authenticate with their own accounts and call the Workspace API directly. See External Identity Providers for setup guides.

Public Access

Entities can be configured for unauthenticated access. See API Settings for details.