# Gigstereo auth.md

Audience: AI agents and assistants acting for a person who wants to find or hire
event services in Colombia.

## Without registration

Public data and quote requests need no credentials: the MCP server
`https://gigstereo.com/mcp` and the read-only REST API `https://api.gigstereo.com/api`
(OpenAPI: https://gigstereo.com/openapi.json) are open.

## Registering an agent for a user's account

To read the user's requests and reply to providers, use `https://gigstereo.com/mcp/cuenta`
with OAuth 2.1:

1. Discover: `https://gigstereo.com/mcp/cuenta` answers 401 with
   `WWW-Authenticate: Bearer resource_metadata="https://gigstereo.com/.well-known/oauth-protected-resource/mcp/cuenta"`;
   the authorization server metadata is at https://gigstereo.com/.well-known/oauth-authorization-server.
2. Register your agent (RFC 7591, open): `POST https://gigstereo.com/oauth/register` with
   `redirect_uris` (https, loopback http or a private-use scheme) and `client_name`.
   Public clients use `token_endpoint_auth_method: "none"`; `client_secret_post` and
   `client_secret_basic` are also supported.
3. Send the user to `https://gigstereo.com/oauth/authorize` (authorization code, PKCE S256 required,
   `resource=https://gigstereo.com/mcp/cuenta`). They sign in on gigstereo.com and approve the scopes:
   - `requests:read` — Read the user's quote requests and the providers' replies
   - `messages:write` — Reply to providers in the user's chats, after the user approves the text
4. Exchange the code at `https://gigstereo.com/oauth/token`. Access tokens last 1 hour; refresh
   tokens rotate on every use and last 60 days.
5. Send `Authorization: Bearer <access_token>` to `https://gigstereo.com/mcp/cuenta`.

## Registering without a browser redirect (auth.md agentic registration)

For agents that can't receive a redirect (CLI or headless agents), the auth.md
"service_auth" method gives the same tokens:

1. `POST https://gigstereo.com/agent/identity` with
   `{"type":"service_auth","login_hint":"<the user's email>","client_name":"<your agent>"}`.
   The response has a `claim_token` (keep it in memory only) and a `claim` block with
   `user_code` and `verification_uri`.
2. Tell the user: open `verification_uri`, sign in to Gigstereo with that email, and type the
   6-digit `user_code`. Only that account can complete it; 5 wrong codes burn the attempt.
3. Poll `https://gigstereo.com/oauth/token` every `interval` seconds with
   `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=…`. You get
   `authorization_pending` until the user is done, then an `access_token` plus an
   `identity_assertion` (valid 30 days). The tokens are delivered once.
4. When the code expires (10 minutes; `expired_token`), `POST https://gigstereo.com/agent/identity/claim`
   with `{"claim_token":"…","email":"<same email>"}` for a new one. Registrations expire after 24 hours.
5. For a new access token, `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>`.
   After a disconnect it answers `invalid_grant`: register again.

`anonymous` registration and provider ID-JAGs are not offered (`anonymous_not_enabled`,
`issuer_not_enabled`): public tools need no credentials at all.

## Credential use and revocation

Never ask users for their Gigstereo password: they sign in only on gigstereo.com.
Revoke a token at `https://gigstereo.com/oauth/revoke` (RFC 7009). The user can disconnect your
agent from their account page at any time, and a password change disconnects every agent.

## Acting for a user

`request_quotes` shares the user's name and contact with matching providers and
`send_message` writes to a provider in their name: call them only after the user
approves (`userConsent: true` / `userConfirmed: true`).

## Contact

support@gigstereo.com