# redPIM — Agent Authentication

How an AI agent obtains and uses credentials to call the redPIM API
(`https://app.redpim.de/api`). This document follows the emerging `auth.md`
convention (see https://workos.com/auth-md).

## Discover

Authentication is required for every endpoint. When an unauthenticated request is
made, redPIM responds `401 Unauthorized`. The intended discovery hint is a
`WWW-Authenticate` response header advertising the `agent_auth` flow and the
`register_uri`. Machine-readable API surface: https://redpim.de/openapi.json.

## Pick a method

- **Today:** authenticated session cookie (`REDPim.Cookie`) established at login.
- **Roadmap (`agent_auth`):** OAuth 2.0 with PKCE (S256) and scoped permissions,
  plus identity assertion / `id-jag` token exchange for delegated agent access.

Until OAuth ships, headless agents use a per-account **API token** (Bearer).

## Register

Request access for your redPIM account at **me@redcomponents.de**. You receive a
token bound to your department/company scope. (The future `register_uri` will let
agents register programmatically and obtain client credentials.)

## Claim

Exchange your credentials for an access token. With the interim API token there is
no exchange step — the issued token is used directly. Under the planned OAuth flow,
the agent completes the authorization-code + PKCE exchange to claim an access token
and, where delegation applies, an `identity_assertion` (`id-jag`).

## Use the credential

Send the token as a Bearer header on every request:

```bash
curl -H "Authorization: Bearer $REDPIM_TOKEN" \
     https://app.redpim.de/api/Catalog/GetStats
```

## Errors

- `401 Unauthorized` — missing/expired credential. Re-authenticate; honour the
  `WWW-Authenticate` hint.
- `403 Forbidden` — token lacks the required scope for that resource.
- `429 Too Many Requests` — back off and retry.

Error bodies are JSON: `{"error":"<message>"}`.

## Revocation

Tokens can be revoked from your redPIM account (or by contacting
me@redcomponents.de). Revoked tokens immediately return `401`. Rotate tokens
periodically; never embed them in client-side code.