# Authenticating with ZeroPipeline

ZeroPipeline is an API-first CRM. Every capability in the web app is reachable
over HTTP, and agents are a first-class caller: API keys carry an explicit
`agent` role.

- OpenAPI description: https://zeropipeline.ainative.studio/openapi.json
- API catalog: https://zeropipeline.ainative.studio/.well-known/api-catalog
- Capability manifest: https://zeropipeline.ainative.studio/SKILL.md

All paths below are relative to the API origin and already include the
`/api/v1` prefix: `https://zeropipeline.ainative.studio`.

## Which credential should an agent use?

| Credential | Header | Use when |
| --- | --- | --- |
| API key | `X-API-Key: <key>` | Long-lived autonomous agents and server-to-server jobs. Preferred. |
| Bearer JWT | `Authorization: Bearer <access_token>` | You hold end-user credentials, or you completed the OAuth flow. |

Both are declared in the OpenAPI document as the `APIKeyHeader` and
`HTTPBearer` security schemes.

## Option 1 — API key (recommended for agents)

API keys are minted by an already-authenticated principal, so an agent needs
a human to create its first key (or a bearer token from Option 2).

```http
POST /api/v1/api-keys
Authorization: Bearer <access_token>
Content-Type: application/json

{ "name": "my-agent", "role": "agent", "scopes": [] }
```

`role` is one of `agent`, `admin`, or `read-only`. `expires_at` is an optional
UTC timestamp after which the key is rejected.

The response contains the plaintext key **once** — persist it immediately. It
also returns `id`, `prefix`, `role`, `scopes`, and `expires_at`. Thereafter:

- `GET /api/v1/api-keys` lists keys (metadata and `prefix` only, never the secret).
- `DELETE /api/v1/api-keys/{key_id}` revokes a key.

Then authenticate every request with:

```http
GET /api/v1/pipelines
X-API-Key: <key>
```

## Option 2 — email + password, for a token pair

Register (self-serve signup is open):

```http
POST /api/v1/auth/register
Content-Type: application/json

{ "name": "Ada Lovelace", "email": "ada@example.com", "password": "...", "company": "Example Inc" }
```

Log in:

```http
POST /api/v1/auth/login
Content-Type: application/json

{ "email": "ada@example.com", "password": "..." }
```

Returns `{ access_token, refresh_token, token_type: "bearer" }`.

Refresh — note this endpoint takes a single `token` field, not the usual
`refresh_token` field name:

```http
POST /api/v1/auth/refresh
Content-Type: application/json

{ "token": "<refresh_token>" }
```

Other real endpoints: `POST /api/v1/auth/logout`, `POST /api/v1/auth/revoke`,
`POST /api/v1/auth/password-reset/request`,
`POST /api/v1/auth/password-reset/confirm`, and Google sign-in via
`GET /api/v1/auth/google/authorize` + `POST /api/v1/auth/google`.

## Option 3 — OAuth 2.0 authorization code (delegated access)

Use this when your agent acts on behalf of a ZeroPipeline user who is not you.
Register a client with `POST /api/v1/oauth/apps` (requires authentication);
`GET /api/v1/oauth/apps` lists clients and
`DELETE /api/v1/oauth/apps/{app_id}` removes one.

1. Redirect the user to `GET /api/v1/oauth/authorize` with `client_id` and
   `redirect_uri` (both required), plus optional `scope`, `state`, and
   `response_type`. The user is shown a consent screen.
2. On approval the server redirects back with an authorization code.
3. Exchange it at `POST /api/v1/oauth/token`, which is
   **`application/x-www-form-urlencoded`** and takes `grant_type` (required)
   plus `code`, `redirect_uri`, `client_id`, `client_secret`, or
   `refresh_token` depending on the grant.

Also available: `POST /api/v1/oauth/revoke` and `GET /api/v1/oauth/introspect`.

Enterprise tenants additionally have SAML/SCIM provisioning under
`/api/v1/sso/*`, including `POST /api/v1/sso/scim-tokens`.

## Errors

Failures return a stable JSON envelope, not prose:

```json
{
  "error_code": "authentication_error",
  "message": "Not authenticated",
  "details": {},
  "request_id": "826dd960-a658-426e-8773-2cc95951eed2"
}
```

Branch on `error_code` — it is machine-readable and never localized. Quote
`request_id` (also returned as the `X-Request-ID` header) in any support
report. A missing or invalid credential yields `401` with
`error_code: authentication_error`.

## Rate limits

Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and
`X-RateLimit-Reset` (and the un-prefixed `RateLimit-*` equivalents). Read them
and back off rather than retrying blindly; a throttled request returns `429`.

## Payments

Billing is Stripe-backed and completed by a human in the web app. There is no
agent-initiated payment flow: ZeroPipeline does not implement x402, ACP, UCP,
or AP2, and does not issue machine-payable `402` challenges. An agent cannot
purchase a subscription on its own.
