# Rightshold auth.md

For agents, and the people who run them, calling the REST API at https://www.rightshold.com/v1 or the MCP server at https://www.rightshold.com/mcp.

## What needs no credential

License checks, AI-policy reads, KYA and registry lookups, Gate checks, and receipt, manifest and ledger
verification all work without a key. Start with `start_here` (MCP) or `GET https://www.rightshold.com/v1/licenses/check?license=MIT&use=commercial_use`.

## Getting an API key

Each method creates a Rightshold account and returns its API key in the response. Pick one.

1. **Sign up (email optional).** `POST https://www.rightshold.com/v1/accounts/signup` with `{"accept_terms": true}`, optionally
   `display_name` and `email`. MCP tool: `sign_up`.
2. **Key handshake (no email).** `POST https://www.rightshold.com/v1/accounts/signup/handshake/start` with
   `{"accept_terms": true, "public_key_pem": "<Ed25519 public key, PEM>"}`. Sign the returned `payload`
   (its canonical JSON) with the private key and send `POST https://www.rightshold.com/v1/accounts/signup/handshake/complete` with
   `{"signup_id": "...", "signature": "<base64>"}`. The agent's key is proven by the handshake.
   MCP tools: `sign_up_handshake_start`, `sign_up_handshake_complete`.
3. **API bridge (no email).** `POST https://www.rightshold.com/v1/accounts/signup/bridge` with
   `{"accept_terms": true, "endpoint_url": "https://..."}`. Rightshold posts a challenge to that endpoint, which
   must echo it back; the endpoint becomes the account's verified bridge. MCP tool: `sign_up_bridge`.

## Using the key

Send `Authorization: Bearer <api key>` on every request, REST or MCP. Never put the key in a URL. Over MCP a
tool may also take `api_key` as an argument. An agent may also sign its requests with Web Bot Auth
(HTTP Message Signatures); see https://www.rightshold.com/llms.txt.

## Managing keys

- Create another key: `POST https://www.rightshold.com/v1/me/api-keys` with `{"label": "..."}`.
- Revoke one: `POST https://www.rightshold.com/v1/me/api-keys/{key_id}/revoke`.

## OAuth 2.0 clients

If your framework speaks OAuth, it can discover https://www.rightshold.com/.well-known/oauth-authorization-server (RFC 8414) and use
the `client_credentials` grant at `POST https://www.rightshold.com/oauth/token`: send `grant_type=client_credentials` with your API key
as `client_secret` (HTTP Basic or form field; `client_id` is your account id and is optional). The
`access_token` returned is that same API key. No second credential is created, and revoking the key revokes the token.

## Errors and limits

A missing or unknown key on a call that needs one gets `401` with `WWW-Authenticate: Bearer` and a
`resource_metadata` link to the resource's metadata (https://www.rightshold.com/.well-known/oauth-protected-resource). Errors are
`application/problem+json` with a stable `error` code (https://www.rightshold.com/v1/errors). Rate limits: https://www.rightshold.com/v1/limits.