API Authentication

Downcity now uses a single external auth model:

• no username/password sign-in
• no browser session layer
• all external auth goes through Bearer tokens
• tokens are managed by the local CLI on the same machine

The currently exposed endpoints are:

• GET /api/auth/status
• GET /api/auth/me
• GET /api/auth/token/list
• POST /api/auth/token/create
• POST /api/auth/token/delete

Token ownership

Tokens are created and stored on the same local machine that owns the runtime. A token name is only for human identification and management. It does not represent a different token type or channel scope.

Use the token

Send the token through the Authorization header:

If the token is valid, the endpoint returns the current subject, roles, and permissions.

Manage tokens

Token creation, listing, and deletion are local-machine operations. HTTP token-management endpoints require an existing Bearer token, so external callers cannot silently mint authority without first holding authority.

DC_AUTH_TOKEN

Main rule first:

• only external HTTP calls need a Bearer token
• local managed commands now call the local agent daemon over HTTP by default

For direct API usage, the important rule is:

• external calls always authenticate through Authorization: Bearer <token>

Inside the CLI/runtime, the only auth env var most users need is:

HTTP calls that need auth use this resolution order:

1. --token
2. DC_AUTH_TOKEN

So:

• DC_AUTH_TOKEN is the explicit override
• protected HTTP calls normalize DC_AUTH_TOKEN into the Bearer header

If you see Missing bearer token:

• do not start by suspecting sessionId
• first confirm that the target HTTP endpoint is actually protected
• then check whether the current process has any valid token source
• if this happens inside an agent/Bash/ACP subprocess, first check whether the command should receive an explicit token

Concrete token workflows live in Downcity CLI product docs.

Current scope

The current model is intentionally token-only:

• username/password login removed
• bootstrap-admin removed
• login removed
• password/update removed
• Console UI, Chrome extension, and external scripts all use explicitly minted Bearer tokens

Future integrations will stay on this Bearer token model instead of reintroducing a separate login session layer.