DaySurface
REST API

Authentication

API keys, scopes, and access control

When to use an API key

Signing in through an MCP client is the default. Claude, ChatGPT and other MCP clients connect to /mcp and sign the user in through DaySurface's OAuth 2.1 server. They receive short-lived session tokens: a 1-hour access token and a single-use refresh token that rotates on every refresh. The sign_out tool revokes them all. Use this whenever a person is present to sign in.

API keys are for non-interactive clients only. Scripts, CI jobs, server-to-server integrations and MCP clients that can only send a fixed header cannot open a browser to complete an OAuth sign-in. API keys exist for those cases. They work on both the REST API on this page and /mcp.

Because an API key is a long-lived secret rather than a session token, it is constrained:

  • Creating one requires an authenticated caller, and its scopes cannot exceed the caller's.
  • Give it the narrowest scope template that works, and set expires_in_days.
  • DaySurface stores only a SHA-256 hash of the key; the full key is shown once, at creation.
  • An expired or revoked key is refused immediately. Revoke a key the moment it is no longer needed (see Revoke a key).

The REST API also accepts a WorkOS-issued bearer token (Authorization: Bearer) for enterprise SSO. DaySurface's MCP session tokens are for /mcp only.

API Key Authentication

Include your API key in the X-API-KEY header:

curl -H "X-API-KEY: sk_..." \
  https://api.daysurface.com/api/v1/auth/me
{
  "user_id": "user_01abc",
  "email": "[email protected]",
  "auth_method": "api_key"
}

Enterprise SSO via WorkOS is also supported.

Managing API Keys

Create a key

curl -X POST https://api.daysurface.com/api/v1/auth/api-keys \
  -H "X-API-KEY: sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "my-integration", "scope_template": "standard", "expires_in_days": 90}'

Use a scope template for common permission sets:

TemplateWhat it allows
read_onlyRead config and billing info
standardRead + execute tools + manage billing
adminEverything

Or provide explicit scopes:

{ "name": "limited-key", "scopes": ["services:read", "services:execute"] }

List your keys

The endpoint is cursor-paginated. Pass limit (1-100, default 20) and follow next_cursor until has_more is false:

curl -H "X-API-KEY: sk_..." \
  "https://api.daysurface.com/api/v1/auth/api-keys?limit=20"
{
  "items": [
    { "id": 42, "key_prefix": "sk_ab12cd34", "name": "my-integration", "revoked": false }
  ],
  "next_cursor": "eyJjIjoiMjAyNS0wMS0xNVQxMDozMDowMCswMDowMCIsImkiOjQyfQ",
  "has_more": true
}

Fetch the next page by passing the cursor back verbatim (treat it as opaque):

curl -H "X-API-KEY: sk_..." \
  "https://api.daysurface.com/api/v1/auth/api-keys?cursor=eyJjIjoiMjAyNS0wMS0xNVQxMDozMDowMCswMDowMCIsImkiOjQyfQ"

Cursor pagination (rather than offset/page) avoids duplicate rows under concurrent writes and offset drift. It does not provide a point-in-time snapshot, so keys created after the walk starts can still be missed by a later page fetch. Pass the same limit value on each request until has_more is false.

Revoke a key

curl -X DELETE -H "X-API-KEY: sk_..." \
  https://api.daysurface.com/api/v1/auth/api-keys/{key_id}

Scopes

Each API key has scopes that control what it can do:

ScopeDescription
services:readRead tool metadata
services:executeCall tool endpoints
billing:readView usage and subscription info
billing:writeReport usage
admin:readRead admin data
admin:writeAdmin operations

No HTTP endpoint currently requires admin:read or admin:write. Administrative functions (config, doctor) are CLI-only - they have no REST route, so they cannot be reached over the network regardless of scope. Use the daysurface CLI (daysurface config …, daysurface doctor) for those operations. The admin:* scopes remain defined so existing keys that carry them stay valid.

Wildcards: * grants all scopes, services:* grants all service scopes.

A new key's scopes cannot exceed the creating key's scopes (no privilege escalation).

En esta página