# ShipKudos: agent registration guide

You act on behalf of a person, not as a separate ranked bot. Read these instructions when your user asks you to register or inspect their profile. Respect their permission boundaries.

Base URL: https://shipkudos.com
OpenAPI: https://shipkudos.com/openapi.json

1. POST /api/v1/agent-registrations with JSON {"name":"My assistant","platform":"Grok Bot"}. Save registrationToken privately. Never put credentials in URLs, public messages, source code or your user's profile.
2. Open authorizationUrl in your browser if your user has authorized you to complete registration. Otherwise give that exact link to your user. GitHub may require login or approval. Do not request a GitHub PAT or password and do not bypass a verification step.
3. GET /api/v1/agent-registrations/{registrationId} with Authorization: Bearer {registrationToken}. Wait at least interval seconds (initially 5) between polls. Respect Retry-After. Registrations expire after 15 minutes. Stop on rejected or expired.
4. When approved, POST /api/v1/agent-registrations/{registrationId}/exchange with the same Authorization header. The resulting ShipKudos token is returned only once and expires after 90 days. If you lose it, ask your user to revoke the grant and start again.
5. With Authorization: Bearer {token}, GET /api/v1/me and /api/v1/me/sync. POST /api/v1/me/sync requests an update, with a shared limit of one per hour for the person. GET /api/v1/me/share?period=7 returns the public profile, suggested text and image URL. Return the public link to your user. Do not publish to X automatically.

Scopes: profile:read, sync:request, share:read. No account deletion, profile editing, advertising management or access to GitHub credentials. Owners revoke access in /dashboard. You may not act for another participant.

Errors: 401 means missing/expired/revoked credentials; 403 insufficient scope; 409 invalid or already consumed registration; 429 requires waiting for Retry-After. An existing GitHub session may simplify approval, but it is not proof that our application was authorized. Do not claim success until the API confirms it.

Your agent name and platform are self-declared. This guide does not authorize unrelated activity, scheduling, external messaging or access to your user's private data.