# Pirate Skills auth.md – authentication for agents

Pirate Skills has public tools that need no credential, and tools about one person (their wallet, registrations, bookings, Forge sessions) that act as that person. This page says how an agent gets the right credential.

## Discover

- Protected-resource metadata (RFC 9728): https://pirateskills.com/.well-known/oauth-protected-resource – and for the MCP server, https://pirateskills.com/.well-known/oauth-protected-resource/mcp
- Authorization-server metadata (RFC 8414): https://pirateskills.com/.well-known/oauth-authorization-server, mirrored from the issuer https://clerk.pirateskills.com
- OpenID Connect discovery: https://pirateskills.com/.well-known/openid-configuration
- When the MCP server at https://pirateskills.com/mcp needs a sign-in it answers 401 with a `WWW-Authenticate: Bearer resource_metadata="…"` header pointing at its metadata.
- The HTTP API is described in https://pirateskills.com/openapi.json, with both security schemes.

## Pick a method

1. **No credential** – the public tools (`search_knowledge`, `list_events`, `get_offers`) work without one, free.
2. **OAuth sign-in** (Claude.ai, ChatGPT, Cursor and other MCP clients) – the person signs in with their Pirate Skills account in their browser. Use this whenever a person is present.
3. **API key** (scripts, cloud sessions, the CLI, headless agents) – a key the person made themselves. Use this when nobody can click through a sign-in screen.

Not offered: agent-to-agent identity assertions (`agent_auth`, `identity_endpoint`, `identity_assertion`, ID-JAG / `id-jag`) and machine-only service credentials (`service_auth`). Every signed-in call acts for one real person.

## Register

- **OAuth:** clients register themselves (dynamic client registration) at the `registration_endpoint` in the authorization-server metadata – https://clerk.pirateskills.com/oauth/register. Use the authorization-code flow with PKCE (S256).
- **API key:** nothing to register. The person signs in at https://pirateskills.com, opens Settings → Manage account → API keys (https://pirateskills.com/lab/settings), adds a key with a name and an expiry, and copies it – it is shown once.

## Claim

There is no separate claim step: the OAuth consent screen is where the person approves the client, and an API key is already the person's own.

## Exchange

- **OAuth:** send the person to https://clerk.pirateskills.com/oauth/authorize with `response_type=code`, your `client_id`, a PKCE `code_challenge` and `scope=openid profile email`; exchange the code at https://clerk.pirateskills.com/oauth/token. Refresh tokens come with `offline_access`.
- **API key:** no exchange – the key is the bearer token.

## Use the access_token

Send it as a bearer token on every call:

```
Authorization: Bearer <access_token or API key>
```

- MCP: https://pirateskills.com/mcp (Streamable HTTP)
- HTTP: `POST https://pirateskills.com/api/public/agent/tools/{tool}` with the tool's input as JSON

What the person may do depends on their account (their tier and pass), not on the scopes: the scopes only let us know who they are. Each signed-in tool call costs gold from the person's wallet; a tool that changes something asks the person first.

## Errors

- **401** – no credential for a tool that needs one, or the token is invalid, expired or revoked. Start again at Discover.
- **402** `out_of_gold` – the person's wallet is empty; nothing ran.
- **403** – the person's tier does not include this tool, or a write came from a browser session on another site.
- **429** – too many requests from one address this minute; wait and retry.

Every error is JSON: `{ "ok": false, "error": "…" }`.

## Revocation

- **OAuth:** revoke a token at https://clerk.pirateskills.com/oauth/token/revoke.
- **API key:** the person deletes it under Settings → Manage account → API keys; it stops working at once.

More: https://pirateskills.com/docs/sign-in