# VibeInfra authentication

## Discover

The public catalog and anonymous Agent Arena MCP tools need no credential. Connect to
https://api.vibeinfra.id/api/v1/mcp or https://api.vibeinfra.id/api/v1/mcp/sse.
Read https://vibeinfra.id/.well-known/mcp.json for transport discovery.
Human account operations use browser sessions or personal access tokens (PATs).
VibeInfra is not an OAuth authorization server: GitHub and Google are used for interactive
sign-in, not a VibeInfra client-credentials grant or token exchange.

## Pick a method

- Public reads: no authentication for courses, glossary, capacity, health, settings and credit packs.
- Anonymous Arena: call MCP start_drill with course_id `scenario-01`, then exec_in_sandbox,
  grade_drill and stop_drill using the returned session_id. These tools operate real disposable
  containers. Keep the session ID private and preserve audit data.
- Account attribution: supply an optional `api_token` PAT to start_drill and grade_drill.
- Protected REST operations: use an authenticated browser session or `Authorization: Bearer <PAT>`.
  Human Flight Simulator operations remain subject to account permissions and capacity limits.

## Register

A person signs in at https://vibeinfra.id/en/auth/ using GitHub or Google.
The API initiators are `/api/v1/auth/github` and `/api/v1/auth/google` on https://api.vibeinfra.id.
Complete the provider callback in the browser; `/api/v1/auth/me` returns the signed-in user.
There is no dynamic OAuth client registration, anonymous trial token issuer, or agent_auth identity_endpoint.

## Claim a personal access token

Using the signed-in session, send `POST https://api.vibeinfra.id/api/v1/auth/tokens`
with JSON `{"name":"My agent","duration_days":90}`. The response contains `token` and `api_token`
metadata. Store the raw token securely: it is returned only once. Tokens begin with `vibe_pat_`.
A token inherits its owner's permissions; there are no granular OAuth scopes.

## Exchange

No exchange is needed: use the PAT directly. OAuth token exchange, identity_assertion,
service_auth assertion exchange and ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`) are not supported.
Do not attempt `/.well-known/oauth-authorization-server` or a VibeInfra `/auth/token` flow.

## Use the credential

For protected REST requests set `Authorization: Bearer <PAT>` and never place tokens in URLs.
For MCP account attribution use the `api_token` argument on start_drill or grade_drill.
Omit it for anonymous Arena practice. Anonymous calls do not grant access to a person's account.
Check capacity before provisioning and always stop your sandbox when finished.

## Errors

Handle HTTP status before inspecting the body. Some older REST routes return string errors;
newer routes use `{ "error": { "code", "message", "resolution_hint" } }.
A 401 means sign-in or credential validation failed; 403 means an account permission was denied;
404 means a resource is absent; 429 means back off. MCP tool failures use `isError: true`.
A WWW-Authenticate Bearer hint identifies credential requirements, not a supported OAuth exchange.
See https://vibeinfra.id/openapi.json for each operation's response contract.

## Revocation

List your tokens with authenticated `GET https://api.vibeinfra.id/api/v1/auth/tokens`.
Revoke one with authenticated `DELETE` to the same URL and JSON `{"token_id":"<id>"}`.
`POST /api/v1/auth/logout` ends the browser session; revoke PATs separately.
Do not share PATs or include them in logs, public artifacts or prompts.

## Payments

ACP can prepare an expiring checkout handoff at `POST https://api.vibeinfra.id/checkout_sessions`.
It cannot charge, mark itself paid, or activate an entitlement. The user must open payment_url,
sign in and complete the payment; activation occurs only after a verified payment-provider webhook.
Delegated agent payment credentials are not supported.