# Agent authentication on lorikeetcx.ai

How an agent gets access to Lorikeet's surfaces, and exactly which credentials exist.
Most of what an agent wants here needs no credential at all: signing a person up for the
free trial, booking a demo, asking the support agent a question, and searching the CX + AI
jobs board are all keyless. Only the product MCP server, the one that configures a live
Lorikeet account, is protected, and it uses OAuth 2.1.

This file follows the auth.md convention
([WorkOS spec](https://workos.com/auth-md/docs/auth-md)) and documents what Lorikeet
implements and what it deliberately does not.

## Discover

Machine-readable entry points, all on `https://www.lorikeetcx.ai`:

- `/.well-known/ai-catalog.json` - every agent interface on this domain, typed.
- `/.well-known/api-catalog` - RFC 9727 catalog of the same surfaces.
- `/.well-known/ai-plugin.json` - plugin manifest for the keyless surfaces.
- `/openapi.json` - OpenAPI description of the demo booking API.
- `/openapi-agent-signup.json` - OpenAPI description of the agent sign-up API.
- `https://www.lorikeet.tools/openapi.json` - OpenAPI description of the free CX tools API.
- `/.well-known/mcp/server-card.json` - CX + AI jobs board MCP server (no auth).
- `/.well-known/mcp/product-server-card.json` - product MCP server (OAuth).
- `/llms.txt` - navigation index for this site.

For the protected surface, discovery is RFC 9728:
`https://api.lorikeetcx.ai/.well-known/oauth-protected-resource` returns the protected
resource metadata, naming `https://api.lorikeetcx.ai` as the authorization server.

## Pick a method

- **No credential.** The agent sign-up API (`https://api.lorikeetcx.ai/v1/agent-signup`),
  the free CX tools API (`https://www.lorikeet.tools/api/tools`), the demo booking API (`https://book.lorikeetcx.ai`), the support-agent endpoint
  (`https://api.lorikeetcx.ai/v1/ask/{publishable-key}`) and the
  CX + AI jobs MCP server (`https://cx-jobs.lorikeetcx.ai/api/mcp`) are open. Start here;
  it covers every task that does not involve someone's own Lorikeet account. The
  publishable key in the ask URL is not a secret - it is part of the published path.
- **OAuth 2.1.** The product MCP server at `https://api.lorikeetcx.ai/v1/mcp` speaks
  Streamable HTTP and requires a bearer token. It acts on a specific Lorikeet tenant, so
  it is only useful to an agent operating on behalf of an existing customer.

## Register

An agent can register the person it acts for, with no credential of its own:

- `register_uri`: `POST https://api.lorikeetcx.ai/v1/agent-signup`
- Guide first: `GET https://api.lorikeetcx.ai/v1/agent-signup` returns what to ask, the
  rules and what happens next. It creates nothing.
- Shape: `verified_email`, verified by the human. Send the person's confirmed work email,
  first and last name, and optionally `companyWebsite` and `workspaceName`. Lorikeet emails
  the person a sign-up link, valid for 7 days; the account only exists once they open it,
  which proves they own the mailbox. Personal mailboxes are rejected
  (`400 work_email_required`), as on the web sign-up.
- Optional password: with the person's agreement, generate a new random password (20 to 64
  printable ASCII characters, with lower case, upper case and digits), show it to them, and
  send it as `password` with `personApprovedPassword: true`. The link then signs them
  straight in. Never send a password they use elsewhere, and do not keep it afterwards.
- The response is `202` whether or not an email was sent, so registration cannot be used
  to check who has an account. Send it once; a repeat does not send a second email.

Full description: `https://www.lorikeetcx.ai/openapi-agent-signup.json`.

The agent never receives a session, token or API key from this flow, and never pays: the
person adds their own card at checkout to start the 30-day free trial.

The keyless surfaces need no registration of any kind. Partnership and integration
enquiries: `partners@lorikeetcx.ai`.

## Claim

The human claims the account in their own browser by opening the email link: they land
on workspace setup with the agent's details filled in, then checkout. There is no
`claim_uri` for agents. If an agent should later act on that account, the user authorizes
it through the OAuth flow below.

## Use OAuth on the product MCP server

The authorization server metadata advertises:

| Field | Value |
|---|---|
| Resource | `https://api.lorikeetcx.ai/v1/mcp` |
| Authorization endpoint | `https://app.lorikeetcx.ai/oauth/authorize` |
| Token endpoint | `https://api.lorikeetcx.ai/v1/oauth/mcp/token` |
| Scopes | `manage:read`, `manage:write`, `tickets:read`, `customers:read`, `lab:write` |
| Bearer method | `header` |
| Signing algorithm | `HS256` |

Send the token as a bearer credential:

```
Authorization: Bearer <access-token>
```

Request the narrowest scope that does the job. `manage:read`, `tickets:read` and
`customers:read` are read-only; `manage:write` edits agent configuration and `lab:write`
creates simulation and test artefacts.

Never send a token to the keyless surfaces - they do not read it and it should not leave
the api.lorikeetcx.ai origin.

## Errors

- `202` on `POST /v1/agent-signup` is **not** an error: an email is sent if the person is
  eligible. Relay the `next` message and do not call again.
- `400` on `POST /v1/agent-signup`: `invalid_request` (fix the named fields),
  `work_email_required` (ask for their work email) or `password_not_supported` (tell the
  person the password will not be used and resend without it). Follow `instructions`.
- `404` on `/v1/agent-signup`: agent sign-up is switched off. Send the person to
  `https://app.lorikeetcx.ai/sign-up`.

- `401` with body `{"error":"invalid_token"}` - the product MCP server was called
  without a valid bearer token. Fetch
  `https://api.lorikeetcx.ai/.well-known/oauth-protected-resource` and run the OAuth
  flow; do not retry unauthenticated.
- `202` on the support-agent endpoint is **not** an error. The agent answers
  asynchronously: the response carries `poll_url`, `conversation_id` and `turn`. Wait
  about ten seconds, then repeat the same request with the returned `cid` and `turn`
  until `status` is `complete`.
- `409` on `POST /book`: the reserved time is gone or the lead already has a booking.
  Follow the message: fetch fresh times and let the human choose again, or confirm the
  existing booking. Never book twice.
- `429`: rate limited. Honour `Retry-After` when present and back off; the keyless
  surfaces are rate-limited per IP.

## Side effects an agent must know about

`GET https://api.lorikeetcx.ai/v1/agent-signup` creates nothing: read it freely.
`POST https://api.lorikeetcx.ai/v1/agent-signup` **sends a real email to the person**, so
call it once and only after they have confirmed their details and asked to sign up.

`GET https://book.lorikeetcx.ai/schema` creates nothing: read it freely.
`POST https://book.lorikeetcx.ai/route` **hands the lead's details to the sales routing
system** and reserves scheduling capacity, so call it once per lead and only after a human
has confirmed their details and asked for a demo. `POST https://book.lorikeetcx.ai/book`
**creates a real booking and sends a real calendar invite**. Never call `/route` or `/book`
to test a flow; `/schema` and `/openapi.json` are the safe surfaces to explore. Likewise,
never call `POST /v1/agent-signup` for anyone who has not asked to sign up.

## Revocation

A user revokes an agent's access from their Lorikeet account; the token stops working
immediately at the resource server. There is no agent-initiated revocation endpoint. The
keyless surfaces have nothing to revoke; they are rate-limited per IP instead. An unused
agent sign-up link simply expires after 7 days.

## What Lorikeet deliberately does not implement

- No `agent_auth` metadata block on the authorization server.
- No Web Bot Auth directory (`/.well-known/http-message-signatures-directory`): Lorikeet
  does not sign outbound agent requests, so publishing a key directory would assert a
  capability that does not exist.
- No A2A agent card: the support-agent endpoint is plain HTTP, not the A2A protocol.
- No sandbox tenant. Simulations run inside a real account under `lab:write`.
- No agent-held credential from sign-up: registration hands the account to the human, not
  the agent.

Product documentation at `docs.lorikeetcx.ai` is private and requires a customer login;
it is not an agent-reachable surface.