# Authenticating agents to abagraph

This document tells an autonomous agent how to authenticate to abagraph. It
follows the WorkOS `auth.md` convention for agent authentication
(<https://workos.com/auth-md>). abagraph is in early access; this page is
honest about what is live today and what is on the roadmap.

## Discover

An agent discovers how to authenticate in two ways:

1. By calling the API. An unauthenticated request to `/api` returns `401` with
   a `WWW-Authenticate` header pointing at the protected-resource metadata:

   ```
   WWW-Authenticate: Bearer resource_metadata="https://abagraph.com/.well-known/oauth-protected-resource"
   ```

   The referenced RFC 9728 document names the resource and its authorization
   server, and links back to this `auth.md`.

2. By fetching this file directly at `https://abagraph.com/auth.md`. It is also
   advertised as the `agent_auth.skill` in
   `https://abagraph.com/.well-known/oauth-authorization-server`.

## Pick a method

Today abagraph uses **per-tenant Bearer API keys**. A key is bound to a single
tenant subdomain (for example `https://nas.abagraph.com`) and works only there;
an admin token bypasses tenant scope.

Full OAuth 2.0 with `identity_assertion` (including JWT-authorization-grant,
`urn:ietf:params:oauth:token-type:id-jag`, i.e. `id-jag`) is on the roadmap and
**not yet live**. The authorization-server metadata advertises both an
`anonymous` (`api_key`) path and an `identity_assertion` path so agents can plan
ahead, but only the `api_key` credential type is accepted right now. Pick the
API-key method.

## Register

API keys are provisioned through **early-access onboarding** at
<https://abagraph.com>. There is **no public self-serve OAuth flow** and **no
programmatic `register_uri`** yet: an agent cannot dynamically register a client
today. Request a key for your tenant via onboarding or by emailing
<hello@abagraph.com>. When OAuth dynamic registration ships, a `register_uri`
will be added to the authorization-server metadata.

## Claim

Once onboarding issues a key, that key **is** your credential — there is no
separate claim/exchange step today (no `id-jag` assertion exchange yet). Store
the key as a secret. Because tenancy is subdomain-bound, the key you receive is
scoped to exactly one tenant host (e.g. `nas.abagraph.com`) and is rejected on
any other subdomain.

## Use the credential

Send the key in the `Authorization: Bearer <key>` header against your tenant
subdomain. Example, building a context packet:

```bash
curl -X POST https://nas.abagraph.com/api/context \
  -H "Authorization: Bearer $ABAGRAPH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seeds": ["Creator:maya"],
    "goal": "brief me on Maya before our sync",
    "token_budget": 80
  }'
```

A tenant key sent to the wrong subdomain is denied. Alternatively, exchange the
key for an `HttpOnly` session cookie via `POST /api/session {"key": "<key>"}`
for browser-style sessions.

## Errors

- Unauthenticated calls to `/api` return `401 Unauthorized` with the
  `WWW-Authenticate: Bearer resource_metadata="..."` header described under
  Discover.
- A wrong, revoked, or out-of-tenant key is rejected.
- Errors are returned as structured JSON:

  ```json
  { "error": { "code": "unauthorized", "message": "missing or invalid bearer token" } }
  ```

## Revocation

Keys are rotated and revoked out of band: through the console
(credentials provisioned by the managed service) or by contacting
<hello@abagraph.com>. There is no self-serve token-revocation endpoint yet. To
roll a compromised key, request rotation and update the secret your agent reads.