Authentication

Sume Public API v1 uses API keys. Send the key from trusted server-side code with a Bearer token.

Authorization: Bearer sume_live_...

Legacy dashboard-issued keys may also work with X-Api-Key, but Bearer auth is the preferred format for new integrations.

Workspace scoping

Every API key resolves to one user/workspace context. Public API requests should not include identity overrides.

curl https://www.sume.so/api/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"

Use /me to verify:

Field	What it tells you
user	The authenticated Sume user context.
workspace	The workspace scoped to the key.
api_key	Sanitized key metadata, such as prefix/scopes when available.

Do not send workspace_id, user_id, email, or owner information in request bodies. Sume derives access from the key and only returns workspace-visible records.

CLI login

For local use, the CLI can create and store a scoped key through browser login:

sume login
sume me
sume auth status

On remote machines:

sume login --no-browser

The CLI stores local config in ~/.sume/config.json with owner-only file permissions.

Environment setup

Environment variables override local config and are preferred for CI and agents:

export SUME_API_KEY="sume_live_..."
export SUME_API_BASE_URL="https://www.sume.so/api/v1"

Manual local setup:

sume setup --api-key "$SUME_API_KEY"
sume setup --base-url "https://www.sume.so/api/v1"

Secrets checklist

• Store API keys in server-side secret managers or CI secrets.
• Do not put API keys in browser code, mobile apps, screenshots, public issues, or logs.
• Rotate keys if exposed.
• Use separate keys for production, staging, local testing, and automation when possible.
• Redact full signed URLs, request ids, raw auth output, user emails, workspace ids, and API key ids before sharing logs.

Authorization failures

Common responses:

Status	Meaning
401	Missing, malformed, revoked, or unknown API key.
403	The key is valid, but the workspace lacks access to the requested feature or record.
429	The workspace or key is being rate limited.

Use request_id from an error response when asking Sume support to investigate.