# Constile auth.md

How agents get credentials for Constile. An agent working for a Constile publisher or advertiser registers here for a
key that reads the account's reports, and an owner of the account approves it. An assistant reading a publisher's
page needs no credentials.

## Audience

- Agents working for a Constile publisher or advertiser, such as an assistant asked about earnings or ad spend.
- AI assistants that read publishers' pages and receive Constile ads (see the last section).

## Discovery

- Protected resource metadata (RFC 9728): https://constile.app/.well-known/oauth-protected-resource
- Authorization server metadata (RFC 8414), with the `agent_auth` block: https://constile.app/.well-known/oauth-authorization-server

The `agent_auth` block uses the field names of the auth.md recipe at isitagentready.com (`register_uri`, `claim_uri`).
Registration is also a standard OAuth device authorization grant (RFC 8628), so an OAuth client can use
`device_authorization_endpoint` and `token_endpoint` instead.

## Register

Method: `identity_assertion` with `verified_email`. Constile verifies the email itself: the person signs in to Constile
with it. Credential type: `api_key`. Scope: `reports:read`.

```
POST https://constile.app/agent/auth/register
Content-Type: application/json

{"identity_type": "identity_assertion", "assertion_type": "verified_email",
 "email": "person@example.com", "agent_name": "Your agent's name"}
```

Form encoding works too. `email` is the address the person signs in to Constile with; `login_hint` is accepted in its
place. The person sees `agent_name`. The answer:

```json
{"device_code": "...", "user_code": "BCDF-GHJK", "verification_uri": "https://constile.app/connect",
 "verification_uri_complete": "https://constile.app/connect?code=BCDF-GHJK", "expires_in": 600, "interval": 5}
```

Constile sends no email. Show the person `user_code` and `verification_uri`, or the complete link. They sign in with
Google or their password, choose the account, and approve or decline. Only an owner of the account, signed in with
that email and with the email confirmed, can approve.

## Claim

Poll every `interval` seconds:

```
POST https://constile.app/agent/auth/claim
Content-Type: application/json

{"device_code": "..."}
```

The OAuth form of the same call is `POST https://constile.app/oauth/token` with
`grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=...`.

Until the person answers, the answer is 400 with `error` set to `authorization_pending`, or `slow_down` when you poll
faster than `interval`. Then it's 400 with `access_denied` if they declined, `expired_token` after 10 minutes, or 200:

```json
{"access_token": "constile_api_...", "token_type": "Bearer", "scope": "reports:read", "credential_type": "api_key",
 "account": {"id": "org_...", "name": "...", "kind": "publisher"}}
```

The key is given once. Store it as a secret.

## Using credentials

```
Authorization: Bearer constile_api_...
```

The key reads `GET /v1/reports`, up to 60 requests a minute, and nothing else. A missing or wrong key gets 401 with
`WWW-Authenticate: Bearer resource_metadata="https://constile.app/.well-known/oauth-protected-resource"`.

## Revoking

`POST https://constile.app/oauth/revoke` with `token=constile_api_...` revokes the key (RFC 7009). The account's owners see it under
API in the dashboard, named for the agent, and can revoke it there. A key also stops working when its account closes.

## Keys made in the dashboard

- API key, starting `constile_api_`: the same kind of key, made by a person at
  https://constile.app/p/api (publishers) or https://constile.app/a/api (advertisers). An account can have up to 10 live keys.
- Conversion key, starting `constile_conv_`: https://constile.app/a/conversions, for `POST /v1/conversions`. Agents can't register
  for one. An advertiser account has one; replacing it stops the old one at once.

## Assistants receiving ads

No registration. When a publisher's page carries an ad, its response names the ad's machine-readable form in a
`Constile-Offer` header and in `Link: <...>; rel="sponsored-access"`. The ad's links carry their own token, so
following one is the credential. Sign requests with HTTP Message Signatures (Web Bot Auth) and send `Signature-Agent`;
Constile also recognizes assistants by user agent, by network, and by the IP ranges their operators publish. An ad
made to an assistant verified by its published addresses or its network can be taken only by a request Constile
verifies as that assistant; any other request gets 403.

To have an assistant recognized and verified, its operator can write to hello@constile.app.

## More

- API catalog: https://constile.app/.well-known/api-catalog
- OpenAPI description: https://constile.app/openapi.json
- Developer docs: https://constile.app/developers
