API authentication

Every operation in the reference names the scheme it accepts, in a security block and in its code samples. This page says what each of those schemes is and how a caller gets one.

The console session

Most calls to a Depot come from the console in a browser. The credential is one thing in two parts.

Scheme	Sent as	How it is obtained
consoleSession	The outpost_console cookie	Signing in to the console. The browser sends it. A script cannot set it
csrfToken	The X-Csrf-Token header	Issued with the session. It goes with every request that changes something

Sending the cookie without the header fails on any request that changes state, which is the point. A form on another site can make a browser send the cookie, but it cannot read the token.

Because the cookie is set by signing in, a sample in a language other than curl shows the request with credentials: "include" or its equivalent, not a line that invents a session.

Automation

Scheme	Sent as	How it is obtained
provisionToken	Authorization: Bearer ...	Issued when an installer or an integration is configured

This is the credential an integration holds. It identifies the integration rather than a person, so it carries only the permissions it was granted, and it is revoked where it was created.

Authorization: Bearer <provision-token>

Public routes

Some operations take no credential at all. They are marked in the reference with no permission badge, and where the URL itself is the credential, with Token in the path.

A token in the path means the whole URL is a secret. Do not paste one into a ticket, a chat message or a log line. These routes exist so somebody outside the organisation can answer a survey or read a status page without an account, and the token is what stands in for one.

Agents

An Agent authenticates with neither of the above. It connects to its Depot over gRPC with mutual TLS and is identified by its client certificate, which it receives during enrolment. See the Agent gRPC API.

To do

This page is an outline. It still needs:

• The exact sign in exchange, request by request.
• How long each credential lasts and how it is renewed.
• How a provisioning token is created, scoped and revoked.
• What a caller should do on a 401 compared with a 403.
• Guidance for an AI agent holding a credential on a person’s behalf.