---
title: "API authentication"
description: "The credentials the Depot API accepts, how each one is obtained, and how an Agent authenticates over gRPC."
url: "https://support.outpostplatform.com/api/authentication/"
product: "depot"
type: "reference"
status: "stub"
ai_summary: "Lists the Depot API security schemes. A console session cookie paired with an X-Csrf-Token header, a provisioning bearer token for automation, and public routes whose credential is a token in the URL path. Agents authenticate over gRPC with a client certificate, not with any of these."
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/api/authentication.md"
license: "CC BY 4.0"
---

# 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.

```text
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](/api/generated/grpc/).

## 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.