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. Store them securely. If you lose a key, you'll need to create 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 — you must create a new one
• 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: Create a new key before revoking the old one to avoid downtime. Both keys work simultaneously until you revoke the old one.
• 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

Public Access

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