# Authentication

> Authenticate to the agent metrics API with a Bearer osk_ key, or to the console REST API with the pl_session session cookie from login.
>
> Canonical: https://xdp.network/docs/api-reference/authentication · Updated 2026-08-09

XDP.NETWORK exposes two distinct APIs with two different auth models. The OpenShield
agent metrics API on your own server takes a Bearer API key; the console REST API takes
a session cookie. A credential for one does nothing on the other.

## Agent metrics API: Bearer key

Every request to the agent's metrics API carries an API key that starts with `osk_`.
Print the metrics URL and the key on the server:

```bash
openshield key
```

Send the key in the `Authorization` header:

```bash title="Liveness check (also verifies the key)"
curl -H "Authorization: Bearer osk_..." http://203.0.113.10:9100/health
```

```bash title="Full metrics snapshot"
curl -H "Authorization: Bearer osk_..." http://203.0.113.10:9100/metrics
```

A missing or wrong key returns `401`. A valid key from an IP outside
`metrics.whitelist` returns `403`.

## Console REST API: session cookie or personal token

The console REST API is the same JSON API the dashboard uses in your browser. Two
ways to authenticate:

**Personal access token (best for scripts).** Create one under
*Settings → API* — tokens look like `xdp_…` and are shown once. Send it as a
Bearer header:

```bash title="List your servers with a token"
curl -H "Authorization: Bearer xdp_..." "$CONSOLE/api/servers"
```

Tokens act as your account (same visibility as the web session) and can be
revoked individually at any time.

**Session cookie.** You can also log in with your account email and password; the
response sets a session cookie named `pl_session`. Replace `$CONSOLE` with the base
URL where you open the dashboard:

```bash title="Log in and store the session cookie"
curl -c cookies.txt -X POST "$CONSOLE/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

Send the cookie on every subsequent request:

```bash title="List your servers"
curl -b cookies.txt "$CONSOLE/api/servers"
```

`POST /api/auth/logout` ends the session. Login itself is rate limited — see
[Rate limits](/docs/api-reference/rate-limits).

## Treat keys, tokens, and cookies as secrets

Anyone holding your `osk_` key can read your server's metrics, anyone holding an
`xdp_` token or a live `pl_session` cookie acts as your account. Never commit them
to a repository or paste them into tools you don't control.

:::warning
If an agent key may have leaked, rotate it with `openshield key` and then update the
key saved on the server in the console so the dashboard keeps working.
:::

## Next steps

- [Endpoints](/docs/api-reference/endpoints)
- [Getting credentials](/docs/openshield-xdp/getting-credentials)
- [Errors](/docs/api-reference/errors)