# Claim Github Installation

> Consume a state UUID, fetch installation metadata, write the credential.

Canonical URL: https://docs.botyard.io/docs/api/integrations-github/claim_github_installation_v1_integrations_github_claim_post

`POST /v1/integrations/github/claim`

Consume a state UUID, fetch installation metadata, write the credential.

Authenticated by the state UUID (which was issued to a specific org+user).
Session cookie is optional — if present, defense-in-depth checks
`session.user_id == row.initiated_by_user_id`. If absent (cookie expired
during the GitHub detour), the state alone is sufficient.

All errors raise BotyardError subclasses so the central handler emits
RFC 9457 Problem Details with the right ``error_code`` for the frontend.

## Request body

`application/json`: GitHubClaimRequest (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | yes | UUID returned in the GitHub setup callback |
| `installation_id` | integer | yes | GitHub installation ID from the setup callback |
| `setup_action` | "install" \| "update" \| "request" | yes | Setup action GitHub reports |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Successful Response | GitHubClaimResponse |
| `400` | setup_action is not actionable (e.g. 'request') |  |
| `403` | Session user does not match install initiator |  |
| `409` | Conflict (org or installation already attached) |  |
| `410` | Install state is invalid, expired, or already consumed |  |
| `502` | Upstream GitHub API error while fetching installation |  |
| `default` | RFC 9457 Problem Details error response | ProblemDetails |

Full schemas: operation `claim_github_installation_v1_integrations_github_claim_post` in the OpenAPI spec at https://api.botyard.io/openapi.json.