SchemaStack

Appearance

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:

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

Permission Levels ​

PermissionGETPOSTPUTDELETE
Read & WriteYesYesYesYes
Read OnlyYesNoNoNo

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

OAuth 2.0 ​

For an application acting on behalf of a person who signs in, rather than holding a workspace key of its own. One access token covers both the Workspace API and that workspace's MCP endpoint.

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

Registering an application ​

An administrator registers it in the admin app under Workspace → OAuth2, setting its name, redirect URIs and scopes. That produces a client_id; there is no client secret, because the flow uses PKCE.

An application can also register itself, which is how a hosted AI client — one you only ever give a URL to — takes part at all:

http
POST https://schemastack.io/api/oauth2/register
Content-Type: application/json

{
  "client_name": "My integration",
  "redirect_uris": ["https://example.com/callback"],
  "scope": "workspace:read workspace:write"
}

Registering grants nothing. The application reaches no data until someone signs in and approves it, and the consent screen says plainly when an application registered itself rather than being added by an administrator.

Redirect URIs must be https, or http on loopback for an application redirecting to the machine it runs on.

The flow ​

Authorization Code with PKCE (S256 only):

Authorizationhttps://schemastack.io/admin/oauth2/consent
Tokenhttps://schemastack.io/api/oauth2/token
Revocationhttps://schemastack.io/api/oauth2/revoke
Registrationhttps://schemastack.io/api/oauth2/register
Scopesworkspace:read, workspace:write

Rather than hard-coding those, a client can read them from https://schemastack.io/.well-known/oauth-authorization-server.

Access tokens last an hour; refresh tokens last 30 days and rotate on use. If a refresh token is ever replayed, every token for that application and user is cut off — a replay means one of them was stolen.

Permissions ​

ScopeWorkspace APIMCP
workspace:readGET onlyRead-Only
workspace:writefull CRUDData-Only

An OAuth token cannot reach Full MCP access, so it cannot change your schema. Agreeing to a scope called "write" means letting an application write records, not letting it drop a column. Schema changes need an API key created by an administrator.

Revoking access ​

Workspace → OAuth2 lists the applications with active sessions, including ones that registered themselves, and who granted them. Revoking takes effect immediately — including for a token the application is already holding, not just the next one it would have been issued.

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.

SchemaStack Documentation