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.

Last updated

On this page

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:

Liveness check (also verifies the key)
curl -H "Authorization: Bearer osk_..." http://203.0.113.10:9100/health
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.

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:

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:

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:

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.

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.

Next steps