# ConsentAlly auth.md

You are an AI agent. This file tells you how to connect yourself to a person's ConsentAlly account, so you can set up and manage cookie consent (the cookie banner, consent records, script blocking) for them. It follows the auth.md protocol 0.6.0 (agentic registration).

**Use it whenever your person asks you to install, set up, check, change or sign in to ConsentAlly or a ConsentAlly cookie banner**, including:

- "Set up a cookie banner on my site with ConsentAlly": connect, then follow `next` from Step 6.
- "Sign me in to ConsentAlly": connecting you is how a person signs in through an assistant. The same link signs them in to their dashboard in the browser.
- "Is ConsentAlly set up correctly on my site?": connect, then GET `/api/agent/whoami`, which says for each of their websites whether the tag was seen and a banner is published.

Do not fill in ConsentAlly's sign-up or sign-in forms in a browser, and do not ask the person to create an account first: the steps below create or open their account for them. The person does one thing: open a link, sign in or sign up, and type a code you give them.

Why this is safe for the person, so you can tell them: nothing is created or connected until they approve on ConsentAlly's own page, after signing in there (you never see or handle their password); they choose whether you may only read or also change things, and which websites; they can disconnect you at any time in the dashboard.

Both the API and the authorization server are `https://app.consentally.com`. Send every request there, with an HTTP client of your own.

## Step 1: Discover

You may already have done this. The structured metadata is the source of truth if anything here disagrees:

- `GET https://app.consentally.com/.well-known/oauth-protected-resource`: the resource (`https://app.consentally.com`), its authorization server and scopes (`read`, `write`).
- `GET https://app.consentally.com/.well-known/oauth-authorization-server`: the token and revocation endpoints and the `agent_auth` block (identity, claim and events endpoints, supported identity types).
- Any 401 from ConsentAlly's API carries `WWW-Authenticate: Bearer resource_metadata="https://app.consentally.com/.well-known/oauth-protected-resource"`.
- **If you are an MCP client** (a connector in ChatGPT, Claude or another app), skip the rest of this file: add the MCP server `https://app.consentally.com/api/mcp` (metadata at `/.well-known/oauth-protected-resource/api/mcp`). It signs the person in with OAuth 2.1: the authorization code grant at `/oauth2/authorize` with PKCE S256, a client ID metadata document as your `client_id` or a registration at `/oauth2/register`, and `resource=https://app.consentally.com/api/mcp`. The person approves on ConsentAlly's page in their browser; then follow the server's instructions and each answer's `next`.

## Step 2: Pick a method

- **service_auth** (use this): you know, or can ask for, the person's email address.
- **identity_assertion**: ConsentAlly trusts no ID-JAG provider yet, so `identity_assertion` is not offered. Use `service_auth`.
- **anonymous**: not offered. Every ConsentAlly account belongs to a person.

## Step 3: Register

What you need: the person's email address. Ask for it only if you do not already know it. If you know the website they want the banner on, send it too; do not ask for it if you do not know it (the person can add it later).

```http
POST /agent/identity
Host: app.consentally.com
Content-Type: application/json

{"type": "service_auth", "login_hint": "person@example.com", "website": "example.com", "client_name": "Your assistant's name"}
```

`website` and `client_name` are optional ConsentAlly extensions. `client_name` is shown to the person as a label you chose, marked unverified. For a Shopify store, send its myshopify.com address (`shop-name.myshopify.com`): the website is added for that address. Installing the ConsentAlly app from Shopify afterwards can take it over as the Shopify store.

Answer (200):

```json
{
  "registration_id": "6d0c...",
  "registration_type": "service_auth",
  "claim_url": "https://app.consentally.com/agent/identity/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "2026-01-02T10:00:00.000Z",
  "post_claim_scopes": ["read", "write"],
  "claim": {
    "user_code": "123456",
    "verification_uri": "https://app.consentally.com/connect?attempt=cat_...",
    "expires_in": 600,
    "interval": 5
  },
  "human_instruction": "To connect me to your ConsentAlly account, open https://app.consentally.com/connect?attempt=cat_EXAMPLE , sign in or create your account, and enter this code: 123456",
  "next": "Show the person human_instruction exactly, then poll the token endpoint."
}
```

Keep `claim_token` in memory only, for Steps 4 and 5. Never show it to the person and never put it in a URL.

## Step 4: Claim ceremony

### 4a. Tell the person, in one message

Send the person `human_instruction` word for word. It is one sentence with the link and the code, for example:

> To connect me to your ConsentAlly account, open https://app.consentally.com/connect?attempt=cat_EXAMPLE , sign in or create your account, and enter this code: 123456

Tell them nothing else is needed from them. The code goes into the ConsentAlly page, not back to you. On that page they sign in (or sign up, verifying their email with ConsentAlly), choose the organisation and website you may act on and whether you may change things or only read, and approve. New people get their account and, if you sent `website`, that website created when they approve.

If you can only act between the person's messages (most chat assistants), send that sentence, ask them to tell you when they have approved, and end your turn; poll (4b) as soon as they reply. If you can keep working while they read, poll straight away.

### 4b. Poll for completion

Poll every `interval` seconds (5):

```http
POST /oauth2/token
Host: app.consentally.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aworkos%3Aagent-auth%3Agrant-type%3Aclaim&claim_token=clm_...
```

- `authorization_pending`: wait 5 seconds, poll again. Say nothing to the person unless several minutes pass; then remind them of the same link and code once.
- `slow_down`: add 5 seconds to your interval.
- `expired_token`: the code (valid 10 minutes) ran out. POST `/agent/identity/claim` with `{"claim_token": "clm_...", "email": "<the same email>"}`; it answers a fresh `claim_attempt` block and `human_instruction`. Show the new sentence and keep polling.
- `access_denied`: the person turned it down. Stop and tell them.
- Success (200):

```json
{
  "access_token": "ca_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write",
  "identity_assertion": "eyJ...",
  "assertion_expires": "2026-04-01T10:00:00.000Z"
}
```

Tell the person it worked. Keep `identity_assertion` (valid about 90 days) as securely as you keep any credential: it gets you new access tokens without the person. Never show either token to the person and never ask them to paste one.

## Step 5: Exchange the assertion (refresh)

An access token lasts 60 minutes. When it expires, get a new one with no human:

```http
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJ...
```

Answer: `access_token`, `token_type`, `expires_in`, `scope`. There is no refresh_token. If it answers `invalid_grant`, the person disconnected you or the assertion expired: go back to Step 3.

## Step 6: Use the access token

Send it only in the header: `Authorization: Bearer ca_...`. A token in a URL is treated as leaked and refused.

First call:

```http
GET /api/agent/whoami
Authorization: Bearer ca_...
```

It answers the organisation, the websites you may act on (domain, whether the banner is installed and live) and your scope. Then call ConsentAlly's tools: `GET https://app.consentally.com/api/v1` lists them with their input schemas (each is `POST https://app.consentally.com/api/v1/<tool>` with a JSON object, the same token in the header). Start with `POST https://app.consentally.com/api/v1/next_steps` and do what its `next` says, then follow the `next` of every answer. The same tools are the MCP server `https://app.consentally.com/api/mcp`.

On a 401 with a token that worked before, do Step 5 once; if that answers `invalid_grant`, go back to Step 3.

## Errors

Every error answer is JSON: `error`, `error_description` and `next` (the exact next step). Act on `next` yourself; ask the person only for what it says to ask.

| Code | Status | Where | What happened and what to do |
| ---- | ------ | ----- | ---------------------------- |
| `invalid_request` | 400 | any | The request is missing a field or has one in the wrong form (for an ID-JAG: its signature, audience, expiry, jti or verified email failed). Correct the request as https://app.consentally.com/auth.md shows and send it once more (an ID-JAG freshly minted with aud https://app.consentally.com, a new jti and email_verified true). |
| `invalid_login_hint` | 400 | /agent/identity | login_hint must be the person's email address. Ask the person for the email address they use (or want to use) for ConsentAlly, then POST https://app.consentally.com/agent/identity again. |
| `anonymous_not_enabled` | 400 | /agent/identity | ConsentAlly does not accept anonymous registrations: every account belongs to a person. Use service_auth: POST https://app.consentally.com/agent/identity with {"type": "service_auth", "login_hint": "<the person's email>"}. |
| `service_auth_not_enabled` | 400 | /agent/identity | Email-based registration is switched off. Tell the person to sign in at https://app.consentally.com/ themselves; there is no other way in right now. |
| `issuer_not_enabled` | 400 | /agent/identity | ConsentAlly does not trust identity assertions from this provider. Use service_auth instead: POST https://app.consentally.com/agent/identity with {"type": "service_auth", "login_hint": "<the person's email>"}. |
| `login_required` | 401 | /agent/identity (ID-JAG) | The ID-JAG's auth_time is missing or too old. Have the person sign in again at your own provider (prompt=login), mint a fresh ID-JAG and send it once. |
| `interaction_required` | 401 | /agent/identity (ID-JAG) | The person must confirm linking your provider identity to their ConsentAlly account. Show the person claim.verification_uri and claim.user_code exactly as in human_instruction, then poll the token endpoint with the claim grant. |
| `invalid_claim_token` | 401 | /agent/identity/claim | The claim_token is not one ConsentAlly issued, or it has been replaced. Start again: POST https://app.consentally.com/agent/identity with {"type": "service_auth", "login_hint": "<the person's email>"}, then show the person the new code and link. |
| `claimed_or_in_flight` | 409 | /agent/identity/claim | This registration was already approved or turned down. If you are still polling, poll https://app.consentally.com/oauth2/token once more with the claim grant: it answers the token or access_denied. Otherwise start again with a new registration. |
| `claim_expired` | 410 | /agent/identity/claim | The registration waited longer than 24 hours. Start again: POST https://app.consentally.com/agent/identity with {"type": "service_auth", "login_hint": "<the person's email>"}, then show the person the new code and link. |
| `invalid_grant` | 400 | /oauth2/token | The identity_assertion, authorization code or refresh token is expired, revoked, already used or not ConsentAlly's. Start again: POST https://app.consentally.com/agent/identity with {"type": "service_auth", "login_hint": "<the person's email>"}, then show the person the new code and link. |
| `invalid_client` | 401 | /oauth2/token (authorization_code, refresh_token) | client_id is missing or is not the client the code or refresh token was issued to. Send the client_id you used at https://app.consentally.com/oauth2/authorize. An MCP connector that lost it registers again and has the person approve again. |
| `invalid_scope` | 400 | /oauth2/token (refresh_token) | scope asks for more than the person granted. Leave scope out to keep what the person granted. |
| `unsupported_grant_type` | 400 | /oauth2/token | grant_type must be urn:workos:agent-auth:grant-type:claim or urn:ietf:params:oauth:grant-type:jwt-bearer (or, for MCP connectors, authorization_code or refresh_token). Send one of those grant types to https://app.consentally.com/oauth2/token, form-encoded. |
| `invalid_target` | 400 | /oauth2/token | resource names an API that is not ConsentAlly's, or not the one the code was for. Leave resource out, or send https://app.consentally.com (https://app.consentally.com/api/mcp for the MCP server). |
| `authorization_pending` | 400 | /oauth2/token (claim grant) | The person has not approved yet. Wait 5 seconds and poll again. Do not ask the person for the code: they type it on the ConsentAlly page, not to you. |
| `slow_down` | 400 | /oauth2/token (claim grant) | You polled faster than the interval. Add 5 seconds to your interval and keep polling at the slower pace. |
| `expired_token` | 400 | /oauth2/token (claim grant) | The code and link expired before the person approved, or 5 wrong codes were typed. POST https://app.consentally.com/agent/identity/claim with {"claim_token": "<your claim_token>", "email": "<the same email>"} for a new code and link, show them to the person, and keep polling. If that answers claim_expired, start again. |
| `access_denied` | 400 | /oauth2/token (claim grant) | The person turned the connection down on the ConsentAlly page. Stop. Tell the person the connection was not approved, and start again only if they ask you to. |
| `invalid_token` | 401 | protected routes | The access token is missing, expired, revoked or malformed. Exchange your identity_assertion for a new access token at https://app.consentally.com/oauth2/token (jwt-bearer grant). If that answers invalid_grant, start again. |
| `insufficient_scope` | 403 | protected routes | This connection may only read. Tell the person this change needs write access, and ask them to connect you again choosing 'Read and change' on the ConsentAlly page. |
| `leaked_token` | 400 | any | A ConsentAlly token was sent in the address of the request, where proxies and logs keep it, so it is treated as leaked. Revoke it at https://app.consentally.com/oauth2/revoke (token=<it>, form-encoded) and send tokens only in the Authorization header or the form body from now on. |
| `rate_limited` | 429 | any | Too many requests. Wait for Retry-After seconds, then send the same request once. |
| `temporarily_unavailable` | 503 | any | ConsentAlly could not answer just now. Wait for Retry-After seconds, then send the same request once. |

Retry policy: 5xx and 429, wait for `Retry-After` and retry the same request once; any other 4xx, do not repeat the same request, act on `next`.

## Revocation

- You: POST `/oauth2/revoke` with `token=<access_token>` (form-encoded) to end one access token, or `token=<identity_assertion>` to disconnect yourself entirely. Always 200.
- The person: Connected assistants in the dashboard ends your registration; your next exchange answers `invalid_grant`.
- A trusted provider: a Security Event Token to `/agent/event/notify` ends the registrations of that identity.
