# MuseLovin

MuseLovin is "Sign in with your AI agent" — a passport and identity rail for AI agents.
An app never handles passwords; a human approves one pairing in their agent's chat,
and the app gets a verified agent identity (a stable agent_id plus a bearer token).

> Full API reference for agents and developers: https://muselovin.com/llms-full.txt
> Human-readable docs: https://muselovin.com/developers

## The pairing flow (the whole protocol)

1. The app calls `POST /api/v1/pairings` with its `mlk_` API key and gets a
   6-character code, a claim URL, the requested scopes, and a poll secret.
2. The app shows the human one self-contained sentence. The human pastes it
   into their agent's chat: `Pair me with <AppName> using code <CODE>.
   (Agent: redeem by POSTing ...)` — it names the app and code and tells the
   agent exactly which POST to make, so the agent needs no doc to redeem it.
   The claim URL shows a consent screen first: which app is asking, what it
   will be able to do (the scopes), and whether MuseLovin verified the developer.
3. The agent calls `POST /api/v1/pairings/<CODE>/redeem` with its name and gets
   back a stable `agent_id` (its passport), an `mla_` bearer token, and the
   granted scopes.
4. The app polls `GET /api/v1/pairings/<CODE>` with the poll secret until the
   status is `redeemed`, then binds its session to the verified agent_id.
5. Later, the app verifies any presented agent token server-side with
   `POST /api/v1/tokens/verify` (returns the granted scopes too).
6. If the human granted the `message` scope, the app can reach the agent any
   time with the message pipe: `POST /api/v1/messages` (body: agent_id +
   text, max 4000 chars); the agent fetches with `GET /api/v1/messages` and
   confirms with `POST /api/v1/messages/ack`. At-least-once delivery.
   Without the `message` scope, sending is a 403.

## Scopes (the consent model)

Every pairing carries an explicit grant the human approves — pairing is never
a blank check.

- `identity` — the app can verify the agent's identity. Always granted; it is
  what pairing means.
- `message` — the app can send messages to the agent (the pipe back). Opt-in.

Apps declare the scopes they want at signup (`POST /api/v1/apps`, body field
`scopes`; default is `["identity"]`). Each pairing may request a subset of the
app's registered scopes; requesting an unregistered scope is a 400. The grant
is recorded on the agent's token, and the message pipe enforces it server-side.

That is the entire ceremony. Everything an agent needs to implement either side
is in llms-full.txt: endpoint shapes, auth, curl examples, error codes, and limits.

## Credentials

- App API key (`mlk_...`): identifies the developer app. Issued during the
  private beta — self-serve at https://muselovin.com/signup
- Agent token (`mla_...`): bearer token the agent presents to apps. Scoped to
  one (agent, app) pair. One-year sliding lifetime; re-pairing revokes the old one.
- Poll secret: returned at pairing creation; lets the app watch for redemption.
- Admin secret: bootstraps new apps via `POST /api/v1/admin/apps`.

## Base URL

https://muselovin.com