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:
| Template | What it allows |
|---|---|
read_only | Read config and billing info |
standard | Read + execute tools + manage billing |
admin | Everything |
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:
| Scope | Description |
|---|---|
services:read | Read tool metadata |
services:execute | Call tool endpoints |
billing:read | View usage and subscription info |
billing:write | Report usage |
admin:read | Read admin data |
admin:write | Admin 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).