# auth.md

How an agent authenticates to Seer at https://seer.build.

## There is no OAuth here, and no self-registration

Seer issues one kind of credential: a long-lived workspace API key. There is no
authorization server, no token endpoint, no JWKS, and no dynamic client registration, so
`/.well-known/oauth-authorization-server`, `/.well-known/openid-configuration` and
`/.well-known/oauth-protected-resource` are all absent rather than empty. If you came
here after a failed discovery fetch, this is the end of that search: stop looking and read
the rest of this page.

An agent cannot enrol itself. A key is minted by a signed-in human, and that is deliberate
— a key spends its owner's GitHub access when it publishes a review, so it is a person's
credential lent to an agent rather than an identity of the agent's own.

## Getting a key

A human does this once, in a browser:

1. Sign in at `https://seer.build/login` (Google OIDC).
2. Open the workspace's settings at `https://seer.build/settings/<workspace>`.
3. Mint a key. It is shown exactly once, at mint, and only its hash is stored — there is
   no way to read it back, only to roll or revoke it.
4. They put it in your environment, conventionally as `SEER_API_KEY`.

Keys look like `seer_sk_…`. A key belongs to **one workspace and one person**. Which key
you send is which workspace you publish into; no call names a workspace itself. Someone in
several workspaces holds one key per workspace.

## Using it

Bearer, in the Authorization header. That is the only supported method — no query
parameter, no cookie, no body field.

```sh
curl -X PUT --data-binary @bundle.zip \
  -H "Authorization: Bearer $SEER_API_KEY" \
  https://seer.build/api/bundles/your-slug
```

| you get | it means |
|---|---|
| `401` | no key, or a key that does not resolve. Ask the human for a new one; do not retry. |
| `403` | the act needs a signed-in person rather than a key. Filing a question on a review is the one that does. |
| `404` | the thing is not in your key's workspace. It may exist in another; this reply will not say. |

Browser sessions are the other credential, and they are a person's, not yours. The read
paths accept either; every write that an agent makes takes the key.

## What a key can reach

Everything under `/api/`, scoped to that key's workspace: publishing and listing bundles
and images, publishing and reading reviews, answering annotations, and minting or revoking
share links. The full API is described at `https://seer.build/openapi.json`, catalogued at
`https://seer.build/.well-known/api-catalog`, and explained in prose at `https://seer.build/skill.md`.

Revocation is the human's, at the same settings page. A revoked key stops resolving
immediately; a rolled one returns a new secret and the old one dies with it.