# PigmentaLab auth.md

How an AI agent gets access to PigmentaLab on behalf of a person.

PigmentaLab (https://pigmentalab.io) is a pre-press engine for DTF and textile printing. An agent always acts for a person who has a PigmentaLab account, and what it uses is charged to that person's API credit.

## Who registers

- The person creates their own account at https://pigmentalab.io (Google sign-in). Agents do not create accounts and never see the person's password.
- The agent gets a credential for that account in one of the two ways below.

## Method 1: OAuth 2.1 through the MCP server (recommended)

- Protected resource: `https://mcp.pigmentalab.io/mcp` (MCP, Streamable HTTP).
- A call without a credential gets `401` with `WWW-Authenticate: Bearer resource_metadata="https://mcp.pigmentalab.io/.well-known/oauth-protected-resource/mcp"`.
- Protected resource metadata (RFC 9728): https://mcp.pigmentalab.io/.well-known/oauth-protected-resource/mcp
- Authorization server metadata (RFC 8414): https://mcp.pigmentalab.io/.well-known/oauth-authorization-server (issuer `https://mcp.pigmentalab.io`).
- Client registration: dynamic client registration (RFC 7591) at `https://mcp.pigmentalab.io/register`, or a client ID metadata document (an HTTPS URL as the `client_id`). Public clients are welcome (`token_endpoint_auth_method: none`), and loopback redirect URIs work on any port.
- Authorization code with PKCE (`S256`), scope `pigmenta`, and the `resource` parameter (RFC 8707).
- The person signs in at pigmentalab.io and presses Allow. PigmentaLab then creates a revocable API key for that agent in the person's account, and the agent receives access and refresh tokens tied to it. The person can revoke it at any time at https://pigmentalab.io/app/api.
- Send the access token as `Authorization: Bearer <token>` to `https://mcp.pigmentalab.io/mcp`.

## Method 2: an API key

- The person creates a key at https://pigmentalab.io/app/api (it starts with `plb_live_`).
- REST API (`https://api.pigmentalab.io/v1`): `Authorization: Bearer plb_live_...`
- MCP server: `X-API-Key: plb_live_...` or `Authorization: Bearer plb_live_...`
- MCP clients that cannot send headers: the person creates a personal link at https://mcp.pigmentalab.io/conectar and pastes it as the server URL.
- Keep the key in the client's secret settings. Never ask the person to paste a key into a chat.

## Credit

- 1 credit = USD 0.01. Live price list, no key needed: https://api.pigmentalab.io/v1/pricing
- A tool is charged only when it delivers a result. The person adds credit at https://pigmentalab.io/app/api.
- Errors are JSON with a stable `code`, for example `INVALID_KEY`, `SCOPE_DENIED` or `INSUFFICIENT_BALANCE`.

## More

- Guide for agents and developers: https://pigmentalab.io/mcp
- llms.txt: https://pigmentalab.io/llms.txt
- MCP server card: https://pigmentalab.io/.well-known/mcp/server-card.json
- API catalog (RFC 9727): https://pigmentalab.io/.well-known/api-catalog
- OpenAPI for the REST API: https://pigmentalab.io/mcp/openapi.json
- Agent skill: https://pigmentalab.io/.well-known/agent-skills/pigmentalab/SKILL.md