API Keys And Access

Client applications authenticate to odock-server with Odock API keys. These keys are separate from provider API keys.

API Key Types

An API key can be scoped to:

Fields:

• key: generated by the UI API for normal creates.
• type: organisation, team, or user.
• organisationId
• teamId
• userId
• expiry
• timezone
• revealed
• revoked
• policies

Authentication Headers

The gateway accepts:

Authorization: Bearer <odock-api-key>

or:

X-API-Key: <odock-api-key>

Gemini-compatible clients can also use:

x-goog-api-key: <odock-api-key>

or the Gemini key query parameter.

Auth Cache

The gateway stores API key cache entries in Redis by SHA-256 hash of the raw key. It does not use the raw key as the Redis key.

Cache behavior:

• positive key cache uses AUTH_CACHE_TTL, capped by key expiry;
• negative cache uses AUTH_NEGATIVE_CACHE_TTL;
• after a successful database lookup, policy and model access caches are warmed.

Reveal, Copy, Rotate, Revoke

The UI supports API key actions:

• Reveal: shows the full key only when it has not been revealed before, then marks it revealed.
• Copy: copies the displayed key value.
• Rotate: creates a replacement key with similar ownership and revokes the previous one.
• Revoke: disables the key for future gateway requests.

Because the gateway caches auth results, mutating API keys should trigger cache invalidation. The UI Prisma extension sends invalidation commands when configured.

Model Access

Use model access grants to allow an API key to call a model.

An API key can be linked to one or more models through ApiKeyModelAccess. At runtime:

1. Gateway authenticates the API key.
2. Gateway loads the model access set for the key.
3. Gateway checks that the requested model belongs to the key's organisation.
4. Gateway denies with model_not_allowed if the grant is missing.

MCP Access

MCP access uses ApiKeyMcpAccess:

• one API key,
• one MCP server.

At runtime, the gateway:

1. Authenticates the API key.
2. Resolves the MCP server by ID or slug from the URL.
3. Checks that the server exists, is enabled, and belongs to the organisation.
4. Checks whether the API key has explicit MCP access.
5. Applies server allowed and blocked tool rules.

Access Design Recommendations

Use organisation keys for:

• shared internal services,
• central automation,
• platform-level integrations.

Use team keys for:

• product teams,
• business units,
• separate environments,
• clear usage ownership.

Use user keys for:

• personal developer usage,
• temporary testing,
• low-volume experimentation.

For production applications, prefer team or organisation keys with explicit model and MCP grants.