# Piku auth.md

How an agent gets access to Piku. Two kinds of access:

1. **Brand tools need no sign-in.** `search_creators`, `get_rate_card`, `submit_request`, `get_deal` at https://usepiku.com/mcp answer without a token. Every creator page also reads as https://usepiku.com/{handle}.md and https://usepiku.com/{handle}.json.
2. **Creator tools act for one creator**, with their yes: `list_deals`, `create_quote`, `create_invoice`, `list_invoices`, `get_invoice`, `send_draft`, `get_page`, `design_page`, `list_page_drafts`. They use OAuth 2.1 with Piku as the authorization server.

## 1. Discover

- Call a creator tool on https://usepiku.com/mcp without a token. Piku answers HTTP 401 with `WWW-Authenticate: Bearer resource_metadata="https://usepiku.com/.well-known/oauth-protected-resource/mcp"`.
- Protected resource metadata (RFC 9728): https://usepiku.com/.well-known/oauth-protected-resource/mcp (resource `https://usepiku.com/mcp`) and https://usepiku.com/.well-known/oauth-protected-resource (resource `https://usepiku.com`).
- Authorization server metadata (RFC 8414): https://usepiku.com/.well-known/oauth-authorization-server, issuer `https://usepiku.com`. Its `agent_auth` block points here.

## 2. Register your client

Dynamic client registration (RFC 7591). No account or secret is needed to register:

```http
POST https://usepiku.com/oauth/register
Content-Type: application/json

{"client_name": "Your agent", "redirect_uris": ["https://your-agent.example/callback"], "grant_types": ["authorization_code", "refresh_token"], "token_endpoint_auth_method": "none"}
```

The answer carries your `client_id`. Clients are public: no client secret. Redirect URIs are https, or a loopback address for an app on the person's machine.

## 3. Ask the creator

Send the creator to https://usepiku.com/oauth/authorize with `response_type=code`, `client_id`, `redirect_uri`, `state`, `resource=https://usepiku.com/mcp`, `scope` and PKCE: `code_challenge` (S256 only) and `code_challenge_method=S256`.

| Scope | What it lets you do |
| --- | --- |
| `billing:read` | Read your Deals and Invoices |
| `billing:draft` | Write Drafts of quotes and invoices |
| `billing:send` | Send a Draft after you confirm it in the chat |
| `page:read` | See your page |
| `page:design` | Prepare page designs you apply yourself |

The creator signs in to Piku and approves on the consent screen. They can untick `billing:send`. Piku sends them back to your `redirect_uri` with `code`, `state` and `iss`.

## 4. Get a token

```http
POST https://usepiku.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&code_verifier=...&resource=https://usepiku.com/mcp
```

Access tokens last an hour. Refresh tokens rotate on every use (`grant_type=refresh_token`) and lapse after 30 days unused.

## 5. Use it

Send the token as a Bearer token in the Authorization header, never in the address:

```http
POST https://usepiku.com/mcp
Authorization: Bearer <access_token>
```

A missing, expired or revoked token gets HTTP 401. A tool that needs a scope you were not given gets HTTP 403 `insufficient_scope` with the scopes to ask for: authorize again.

## 6. Revoke

`POST https://usepiku.com/oauth/revoke` with `token` and `client_id` (RFC 7009). The creator can also disconnect any time in Settings > Agents.

## Rules

- Only the creator quotes or accepts. Agents never accept, mark paid, change a Schedule or move money.
- `send_draft` only after the creator says yes to that Draft in the conversation.
- Not supported: identity assertions (ID-JAG), verified email registration and anonymous registration.

More: https://usepiku.com/piku.md (the tools and rules), https://usepiku.com/llms.txt.