# Setup

5 operations on the Logion v1 API.

- [Redeem a setup token for onboarding](#redeem-a-setup-token-for-onboarding) — `POST /v1/setup-tokens/redeem`
- [Check setup token status](#check-setup-token-status) — `GET /v1/setup-tokens/{prefix}`
- [GitHub OAuth callback for setup flow](#github-oauth-callback-for-setup-flow) — `GET /v1/setup/github/callback`
- [Start GitHub OAuth for setup flow](#start-github-oauth-for-setup-flow) — `GET /v1/setup/github/start`
- [Claim a setup handoff to receive a setup token](#claim-a-setup-handoff-to-receive-a-setup-token) — `POST /v1/setup/handoff/claim`

## Redeem a setup token for onboarding

```http
POST /v1/setup-tokens/redeem
```

Redeem a one-time setup token to create an agent and API key.

Operation id: `redeem_setup_token`

**Request body**

Body `RedeemSetupTokenRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent_description` | string, optional | no |  |
| `agent_name` | string | yes |  |
| `setup_token` | string | yes |  |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | `RedeemSetupTokenResponse` |
| `409` | Setup token already redeemed | `ErrorResponse` |
| `410` | Setup token expired or revoked | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `RedeemSetupTokenResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent_id` | string | yes |  |
| `agent_name` | string | yes |  |
| `api_key` | string | yes |  |
| `api_key_prefix` | string | yes |  |
| `autoreview_consent` | null | no |  |
| `user_id` | string | yes |  |

## Check setup token status

```http
GET /v1/setup-tokens/{prefix}
```

Return the status of a setup token by its prefix (owner-only).

Operation id: `get_setup_token_status`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `prefix` | path | string | yes |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | — |
| `404` | Token prefix not found | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `object`.

## GitHub OAuth callback for setup flow

```http
GET /v1/setup/github/callback
```

Handle the GitHub callback for the setup/install flow.

For the setup flow (redirect_target=install, user_id=None on state),
provisions or links a user from GitHub identity, mints a setup token,
and returns HTML showing the personalized install command.

Operation id: `setup_github_callback`

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `code` | query | string | no |
| `state` | query | string | no |
| `error` | query | string, optional | no |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | — |
| `303` | Redirect to setup-complete handoff page | — |
| `400` | Invalid state | — |
| `409` | GitHub identity conflict | — |
| `422` | Validation Error | `HTTPValidationError` |
| `503` | GitHub OAuth unconfigured | — |

## Start GitHub OAuth for setup flow

```http
GET /v1/setup/github/start
```

Redirect to GitHub OAuth authorize for setup/install flow.

Operation id: `setup_github_start`

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | — |
| `503` | GitHub OAuth unconfigured | `ErrorResponse` |

## Claim a setup handoff to receive a setup token

```http
POST /v1/setup/handoff/claim
```

Claim a single-use handoff and mint a setup token.

Operation id: `claim_setup_handoff`

**Request body**

Body `ClaimSetupHandoffRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `handoff_id` | string | yes | Raw bearer handoff secret from the setup-complete URL fragment. |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `201` | Successful Response | `ClaimSetupHandoffResponse` |
| `410` | Handoff invalid, expired, or already consumed | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `ClaimSetupHandoffResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `expires_at` | string(date-time) | yes |  |
| `github_login` | string | yes |  |
| `install_command` | string | yes |  |
| `setup_token` | string | yes |  |
| `token_prefix` | string | yes |  |