# auth.md

You are an agent. **Pixeltable** is multimodal AI data infrastructure (open-source library plus Pixeltable Cloud). This document tells you how to discover protected APIs and register for credentials.

- Open-source library: no auth (`pip install pixeltable`).
- Public agent APIs on this host (`POST https://pixeltable.com/ask`, `POST https://pixeltable.com/mcp`) need no credentials.
- Pixeltable Cloud and other protected APIs use OAuth bearer tokens from WorkOS AuthKit, or dashboard API keys (`X-api-key`).

## Step 1 — Discover

Fetch Protected Resource Metadata, then Authorization Server metadata. The PRM is the machine-readable source of truth; this file is the prose companion.

```http
GET https://pixeltable.com/.well-known/oauth-protected-resource
```

`resource` is `https://pixeltable.com` (use as `aud` if you mint an identity assertion). `authorization_servers` lists the AuthKit issuer. Then:

```http
GET https://signin.pixeltable.com/.well-known/oauth-authorization-server
```

The same document is also published at `https://pixeltable.com/.well-known/oauth-authorization-server` (issuer remains `https://signin.pixeltable.com`). Read `agent_auth` in full: `register_uri` / `identity_endpoint`, `claim_uri` / `claim_endpoint`, and `identity_types_supported`.

OIDC discovery: `https://pixeltable.com/.well-known/openid-configuration` and `https://signin.pixeltable.com/.well-known/openid-configuration`.

## Step 2 — Pick a method

Public `/ask` and `/mcp` — skip registration.

Otherwise, prefer the lightest AuthKit method that fits:

1. **anonymous** — trial access (`pxt:read:public`, `pxt:read:fremium`) with no email and no human step. Claim later if the user wants ownership.
2. **service_auth** — you have the user's email (`login_hint`). Claim ceremony required before tokens.
3. Human fallback — send the user to `https://pixeltable.com/signup`, then create an API key in the dashboard (`X-api-key`).

Do not send `identity_assertion` / ID-JAG unless `identity_types_supported` lists it.

## Step 3 — Register (AuthKit)

Set once:

```bash
ISSUER="https://signin.pixeltable.com"
EMAIL="<user-email>"
```

```bash
# anonymous
REG="$(curl -sS "$ISSUER/agent/identity" -H 'Content-Type: application/json' \
  -d '{"type":"anonymous"}')"

# service_auth (claim ceremony required)
REG="$(curl -sS "$ISSUER/agent/identity" -H 'Content-Type: application/json' \
  -d "{\"type\":\"service_auth\",\"login_hint\":\"$EMAIL\"}")"
```

Errors: `invalid_request`, `invalid_login_hint`, `anonymous_registration_disabled`, `service_auth_registration_disabled`. Do not invent a Pixeltable `/agent/identity` — registration is on the issuer.

## Step 4 — Claim ceremony (service_auth required; anonymous optional)

Mint an attempt and give the user `attempt.verification_uri`. They sign in; the page shows a code. Submit that code with the claim token.

```bash
CLAIM_TOKEN="$(printf '%s' "$REG" | jq -r .claim.token)"
ATT="$(curl -sS "$ISSUER/agent/identity/claim" -H 'Content-Type: application/json' \
  -d "{\"type\":\"service_auth\",\"claim_token\":\"$CLAIM_TOKEN\",\"login_hint\":\"$EMAIL\"}")"
printf '%s' "$ATT" | jq '{verification_uri:.attempt.verification_uri}'

USER_CODE="<code the user read off the claim page>"
VER="$(curl -sS "$ISSUER/agent/identity/claim/complete" -H 'Content-Type: application/json' \
  -d "{\"claim_token\":\"$CLAIM_TOKEN\",\"user_code\":\"$USER_CODE\"}")"
```

## Step 5 — Exchange for an access token

```bash
ASSERTION="$(printf '%s' "$REG" | jq -r .identity.assertion)"
CRED="$(curl -sS "$ISSUER/oauth2/token" -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data-urlencode "assertion=$ASSERTION")"
ACCESS_TOKEN="$(printf '%s' "$CRED" | jq -r .access_token)"
```

Send `Authorization: Bearer $ACCESS_TOKEN`. Tokens are short-lived (~5 minutes); re-exchange from the stored assertion. Refresh via `POST $ISSUER/agent/identity` with `{"type":"refresh","refresh_token":"..."}` when the assertion nears expiry.

Revoke at `https://signin.pixeltable.com/oauth2/revoke`.

## API keys (dashboard)

Humans can sign in at `https://pixeltable.com/signup` and create Cloud API keys. Send `X-api-key: <key>` to Cloud APIs. See https://pixeltable.com/developers/llms.txt.

## More

- Pricing: https://pixeltable.com/pricing.md
- Docs: https://docs.pixeltable.com
- Privacy: https://pixeltable.com/privacy
- Terms: https://pixeltable.com/terms
- API catalog: https://pixeltable.com/.well-known/api-catalog
- Contact: contact@pixeltable.com