# Genaro: set up access for your agent

You are an agent. Your person asked you to set them up with Genaro, which runs image, video, audio and text generation and stores the media, billed from a prepaid balance. Follow these steps in order. They follow WorkOS's auth.md protocol (v0.6.0, https://github.com/workos/auth.md), with the differences listed at the end.

Everything here is at `https://genaro.ai`. You need your person's email address and about two minutes of their time to approve you once in a browser.

If you can add an MCP server that signs in with OAuth (Claude Code, the Claude apps, Cursor and ChatGPT can), there is a shorter way: add `https://genaro.ai/mcp` with no key (Claude Code: `claude mcp add --transport http genaro https://genaro.ai/mcp`), and your client opens your person's browser to approve you on the same Genaro page. Ask your person first, as in Step 0. Follow the steps below when you can't, or need the key for the REST API.

## Step 0: Ask your person first

Before you register, ask your person in one message, and wait for a yes:

> I can connect myself to Genaro so I can generate and store images, video and audio for you. You'll approve it once on a Genaro page, pick the workspace I use, a monthly spending limit (no limit, the default, or $5, $20, $50, $100 or $250 a month) and when my access expires (never, the default, or in 1, 7, 30 or 90 days). With it I can list models and quote prices for free, upload and change your stored media, and start generations, which spend your prepaid balance up to that limit. I can never create or manage API keys. You can disconnect me at any time under Connected agents. Which email do you use for Genaro?

Anyone can sign up for Genaro; your person can create an account when they open the link in Step 3. A new account waits for Genaro to approve it. Meanwhile your person can still approve you and you can finish connecting, but every API and MCP call answers `403 account_pending_approval` until the account is approved, and then the same key just works. The person approving must be an owner, admin or developer of the workspace; whoever signs up owns their own.

## Step 1: Discover (optional)

You can skip this; the endpoints below are fixed. A call to the API without a key answers `401` with `WWW-Authenticate: Bearer resource_metadata="https://genaro.ai/.well-known/oauth-protected-resource"`.

- `GET https://genaro.ai/.well-known/oauth-protected-resource` (RFC 9728) names the resource and its authorization server. The MCP server has its own at `https://genaro.ai/.well-known/oauth-protected-resource/mcp`.
- `GET https://genaro.ai/.well-known/oauth-authorization-server` (RFC 8414) carries the `agent_auth` block: `skill` (this document), `identity_endpoint`, `claim_endpoint` and `identity_types_supported: ["service_auth"]`.

## Step 2: Register with your person's email

```http
POST https://genaro.ai/agent/identity
Content-Type: application/json

{"type": "service_auth", "login_hint": "person@example.com", "agent_name": "Claude Code"}
```

- `login_hint` (required): the email your person gave you. Genaro sends nothing to it; it's shown on the approval page.
- `agent_name` (optional): what your person knows you as, at most 80 characters. It's on the approval card.
- `scope` (optional): space-separated, a subset of `read generate content:write webhooks`. Leave it out to get `read generate content:write`. `read` covers listing and quotes, `generate` starts billable generations, `content:write` uploads and changes stored media, and `webhooks` lets you register webhook endpoints so Genaro tells your app's own address when a generation finishes instead of you polling. Ask for `webhooks` only if you have such an address; it's granted only when you ask, and your person sees it on the card. A webhook endpoint you create belongs to the workspace and is listed with the others.

Response `200`:

```json
{
  "registration_id": "4a0c…",
  "registration_type": "service_auth",
  "claim_url": "https://genaro.ai/agent/identity/claim",
  "claim_token": "gn_claim_…",
  "claim_token_expires": "2026-10-15T18:00:00Z",
  "post_claim_scopes": ["read", "generate", "content:write"],
  "claim": {
    "user_code": "482913",
    "verification_uri": "https://genaro.ai/approve/4a0c…",
    "verification_uri_complete": "https://genaro.ai/approve/4a0c…?code=482913",
    "expires_in": 600,
    "interval": 5
  }
}
```

Keep `claim_token` in memory only. It's returned once, and it's what you collect the key with. Never show it to your person or write it to a file.

## Step 3: Show your person the link and the code

Send one message:

> Open this link, sign in to Genaro, and check the page shows the code **482913**. Then pick the workspace, the spending limit and when my access expires, and press Approve.
> https://genaro.ai/approve/4a0c…?code=482913

Use `verification_uri_complete`. If your person types the link by hand, `verification_uri` asks them for the code instead. The code lives 10 minutes (`expires_in`); the registration lives 24 hours (`claim_token_expires`).

## Step 4: Poll until you have the key

Every `interval` seconds (5):

```http
POST https://genaro.ai/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=gn_claim_…
```

While you wait, the answer is `400` with `{"error": "authorization_pending"}`; keep polling. When your person approves, the answer is `200`:

```json
{"access_token": "gn_live_…", "token_type": "Bearer", "scope": "read generate content:write"}
```

`access_token` is a Genaro workspace API key. It's issued exactly once: a second poll gets `invalid_grant`.

If the code runs out before your person approves, you get `expired_token`. Ask for a fresh code, show it to your person, and go on polling:

```http
POST https://genaro.ai/agent/identity/claim
Content-Type: application/json

{"claim_token": "gn_claim_…"}
```

It answers with a new `claim` block (also as `claim_attempt`). If it answers `410 claim_expired`, the 24 hours are over: go back to Step 2.

## Step 5: Save the key

Save the key where your person keeps secrets, for example a git-ignored `.env` as `GENARO_API_KEY`, or straight into the MCP configuration below. Don't print it back into the conversation, a log or a commit. It stops working when your person revokes it, or at the expiry they chose on the page: the token response then carries `expires_in` (seconds). There is no refresh token; after it expires, register again only if your person asks you to.

## Step 6: Add the MCP server

Genaro's tools are an MCP server at `https://genaro.ai/mcp` (Streamable HTTP, stateless, JSON responses), authenticated with the same key.

Claude Code:

```sh
claude mcp add --transport http genaro https://genaro.ai/mcp --header "Authorization: Bearer <key>"
```

Cursor, in `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json`):

```json
{"mcpServers": {"genaro": {"url": "https://genaro.ai/mcp", "headers": {"Authorization": "Bearer <key>"}}}}
```

Codex, in `~/.codex/config.toml`, with the key in the `GENARO_API_KEY` environment variable:

```toml
[mcp_servers.genaro]
url = "https://genaro.ai/mcp"
bearer_token_env_var = "GENARO_API_KEY"
```

Any other MCP client: a Streamable HTTP server at `https://genaro.ai/mcp` with the header `Authorization: Bearer <key>`. The REST API is at `https://genaro.ai/api/v1` with the same header; its reference is `https://genaro.ai/openapi.yaml`, and `https://genaro.ai/llms.txt` indexes the rest of the documentation.

## Step 7: Make one free check

List the models, which costs nothing:

```sh
curl -s https://genaro.ai/api/v1/models -H "Authorization: Bearer <key>"
```

Over MCP, call the `genaro_list_models` tool. A `200` with a list of models means you're connected; tell your person so.

A `403` whose error type is `account_pending_approval` also means you're connected: the key is saved and correct, but your person's Genaro account is still waiting for Genaro to approve it. Tell your person exactly that, and that you'll work as soon as it's approved. Then stop. Try again later, when your person asks or in a later session, never in a loop, and don't register again: the same key starts working on approval. Never start a generation as a test: generations spend your person's balance. To learn a price, quote it (`POST https://genaro.ai/api/v1/generations/quote`, or the `genaro_quote_generation` tool), which is free.

Once you're connected, you can also build, publish and run Genaro Apps for your person: TypeScript workflows that generate media, call text models and pause for their review. Your key's scopes already cover it (`content:write` publishes, `generate` starts runs). A run spends their balance as it generates, so ask before starting one. How to write one: `https://genaro.ai/docs/apps/llms.txt`.

## Errors

Errors from the sign-up endpoints are JSON, `{"error": "<code>", "error_description": "<what to do>"}`. The API and `/mcp` answer `{"error": {"type": "<code>", "message": "<what to do>"}}`.

| Code | Where | What to do |
|---|---|---|
| `invalid_request` (400) | `/agent/identity`, `/oauth2/token` | Fix the body: `type` must be `service_auth` and `login_hint` an email address. |
| `anonymous_not_enabled` (400) | `/agent/identity` | Genaro has no anonymous trial. Register with `service_auth`. |
| `issuer_not_enabled` (400) | `/agent/identity` | Genaro trusts no ID-JAG issuer yet. Register with `service_auth`. |
| `invalid_claim_token` (401) | `/agent/identity/claim` | Unknown claim token. Go back to Step 2. |
| `claim_expired` (410) | `/agent/identity/claim` | The registration is more than 24 hours old. Go back to Step 2. |
| `claimed_or_in_flight` (409) | `/agent/identity/claim` | Your person already approved (ask `/oauth2/token` for the key) or revoked you (stop). |
| `authorization_pending` (400) | `/oauth2/token` | Not approved yet. Poll again after `interval` seconds. |
| `slow_down` (400) | `/oauth2/token` | You polled too fast. Add 5 seconds to your interval. |
| `expired_token` (400) | `/oauth2/token` | The code ran out. Get a fresh one at `/agent/identity/claim` (Step 4); if that says `claim_expired`, go back to Step 2. |
| `access_denied` (400 or 403) | `/oauth2/token`, `/agent/identity/claim` | Your person denied the request, or the code was mistyped five times. Stop, and register again only if they ask. |
| `invalid_grant` (400) | `/oauth2/token` | Unknown claim token, a key already issued, or the agent was revoked or its access expired. Tell your person; register again only if they ask. |
| `unsupported_grant_type` (400) | `/oauth2/token` | Use `grant_type=urn:workos:agent-auth:grant-type:claim`. |
| `rate_limited` (429) | any | Wait the `Retry-After` seconds, then retry. |
| `account_pending_approval` (403) | `/api/v1`, `/mcp` | Your person's account is waiting for Genaro's approval. Tell them, and try again later; never loop. The key starts working on approval. |
| `account_declined` (403) | `/api/v1`, `/mcp` | Genaro did not approve your person's account. Tell them, and stop. |

On a `5xx`, retry the same request with exponential backoff. On any other `4xx`, don't retry the same request; do what the table says.

## When the key stops working

Your person can revoke you at any time under Connected agents in the Genaro console (`https://genaro.ai/console/agents`), and the key stops working at once. You'll see `401` with a `WWW-Authenticate` header on the API and on `/mcp`. Tell your person, and register again only if they ask you to.

## How this differs from auth.md v0.6.0

- Only the `service_auth` identity type: no `anonymous` registration and no `identity_assertion` (ID-JAG).
- The claim grant returns the credential itself. Genaro issues no identity assertion JWT, so there is no JWT-bearer (RFC 7523) exchange or re-exchange, and no `identity_assertion` in the token response.
- The credential is a Genaro workspace API key, not a short-lived access token: it has no refresh token, and it lasts until your person revokes it under Connected agents or until the expiry they chose at approval (then the token response carries `expires_in`; by default it never expires). There is no `revocation_endpoint` (RFC 7009) and no `events_endpoint` (RFC 8417 security events).
- `verification_uri` names the registration itself rather than a claim-attempt token, and `verification_uri_complete` (from RFC 8628) carries the code, which the approval page shows for your person to compare.
- `/agent/identity/claim` takes only `claim_token`, since the email is fixed at registration.
- At approval your person also picks the workspace, a monthly spending limit (none by default) and an expiry (never by default), which the key carries.
