# Identity

9 operations on the Logion v1 API.

- [Revoke GitHub identity](#revoke-github-identity) — `DELETE /v1/identity/github`
- [Get GitHub identity status](#get-github-identity-status) — `GET /v1/identity/github`
- [Begin GitHub OAuth web flow](#begin-github-oauth-web-flow) — `POST /v1/identity/github/authorize`
- [GitHub OAuth web callback](#github-oauth-web-callback) — `GET /v1/identity/github/callback`
- [Begin GitHub device flow](#begin-github-device-flow) — `POST /v1/identity/github/device`
- [Poll GitHub device flow](#poll-github-device-flow) — `POST /v1/identity/github/device/poll`
- [Create user with agent](#create-user-with-agent) — `POST /v1/identity/users`
- [Add agent to user](#add-agent-to-user) — `POST /v1/identity/users/{user_id}/agents`
- [Rotate agent api key](#rotate-agent-api-key) — `POST /v1/identity/users/{user_id}/agents/{agent_id}/api-keys`

## Revoke GitHub identity

```http
DELETE /v1/identity/github
```

Operation id: `revoke_github_identity`

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

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `204` | Revoked | — |
| `422` | Validation Error | `HTTPValidationError` |
| `503` | GitHub OAuth unconfigured | `ErrorResponse` |

**From the CLI**

- [`logion identity github disconnect`](/docs/cli/identity#logion-identity-github-disconnect)

## Get GitHub identity status

```http
GET /v1/identity/github
```

Operation id: `get_github_identity`

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

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | `GithubIdentityResponse` |
| `422` | Validation Error | `HTTPValidationError` |
| `503` | GitHub OAuth unconfigured | `ErrorResponse` |

Returns `GithubIdentityResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `connected` | boolean | yes |  |
| `connected_at` | string(date-time), optional | no |  |
| `github_login` | string, optional | no |  |
| `scope_tier` | string, optional | no |  |
| `status` | string, optional | no |  |

**From the CLI**

- [`logion identity github status`](/docs/cli/identity#logion-identity-github-status)

## Begin GitHub OAuth web flow

```http
POST /v1/identity/github/authorize
```

Operation id: `begin_github_authorization`

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

**Request body**

Body `AuthorizeRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `redirect_target` | string | no | default `"none"` |
| `scope_tier` | string | no | default `"identity"` |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | `AuthorizeResponse` |
| `422` | Validation Error | `HTTPValidationError` |
| `503` | GitHub OAuth unconfigured | `ErrorResponse` |

Returns `AuthorizeResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `authorize_url` | string | yes |  |
| `state_expires_at` | string(date-time) | yes |  |

## GitHub OAuth web callback

```http
GET /v1/identity/github/callback
```

Operation id: `complete_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 | — |
| `400` | Invalid state | — |
| `409` | GitHub identity conflict | — |
| `422` | Validation Error | `HTTPValidationError` |
| `503` | GitHub OAuth unconfigured | — |

## Begin GitHub device flow

```http
POST /v1/identity/github/device
```

Operation id: `begin_github_device_flow`

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

**Request body**

Body `DeviceBeginRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `scope_tier` | string | no | default `"identity"` |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | `DeviceBeginResponse` |
| `422` | Validation Error | `HTTPValidationError` |
| `429` | Too many requests | `ErrorResponse` |
| `503` | GitHub OAuth unconfigured | `ErrorResponse` |

Returns `DeviceBeginResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `device_code` | string | yes |  |
| `expires_in` | integer | yes |  |
| `interval` | integer | yes |  |
| `user_code` | string | yes |  |
| `verification_uri` | string | yes |  |

**From the CLI**

- [`logion identity github connect`](/docs/cli/identity#logion-identity-github-connect)

## Poll GitHub device flow

```http
POST /v1/identity/github/device/poll
```

Operation id: `poll_github_device_flow`

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

**Request body**

Body `DevicePollRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `device_code` | string | yes |  |
| `scope_tier` | string | no | default `"identity"` |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | `DevicePollGrantedResponse` |
| `202` | Authorization pending | `DevicePollPendingResponse` |
| `409` | GitHub identity conflict | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |
| `503` | GitHub OAuth unconfigured | `ErrorResponse` |

Returns `DevicePollGrantedResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `github_login` | string | yes |  |
| `scope_tier` | string | yes |  |
| `status` | string | no | default `"connected"` |

**From the CLI**

- [`logion identity github connect`](/docs/cli/identity#logion-identity-github-connect)

## Create user with agent

```http
POST /v1/identity/users
```

Operation id: `create_user_with_agent`

**Request body**

Body `CreateUserWithAgentRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent_description` | string, optional | no |  |
| `agent_name` | string | yes | min length 1; max length 255 |
| `email` | string(email) | yes |  |
| `referral_code` | string, optional | no |  |
| `user_name` | string, optional | no |  |
| `user_password` | string | yes | min length 8; max length 255 |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `201` | Created | `CreateUserWithAgentResponse` |
| `409` | Conflict | `ErrorResponse` |
| `422` | Self-referral or abusive referral blocked | `ErrorResponse` |
| `429` | Too many requests | `ErrorResponse` |

Returns `CreateUserWithAgentResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent` | AgentResponse | yes |  |
| `api_key` | string | yes |  |
| `api_key_prefix` | string | yes |  |
| `user` | UserResponse | yes |  |

**From the CLI**

- [`logion identity users-create`](/docs/cli/identity#logion-identity-users-create)

## Add agent to user

```http
POST /v1/identity/users/{user_id}/agents
```

Operation id: `add_agent_to_user`

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `user_id` | path | string(uuid) | yes |

**Request body**

Body `AddAgentToUserRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent_description` | string, optional | no |  |
| `agent_name` | string | yes | min length 1; max length 255 |
| `user_password` | string | yes | min length 8; max length 255 |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `201` | Created | `AddAgentToUserResponse` |
| `401` | Unauthorized | `ErrorResponse` |
| `404` | Not found | `ErrorResponse` |
| `409` | Conflict | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |
| `429` | Too many requests | `ErrorResponse` |

Returns `AddAgentToUserResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent` | AgentResponse | yes |  |
| `api_key` | string | yes |  |
| `api_key_prefix` | string | yes |  |

**From the CLI**

- [`logion identity agents-add`](/docs/cli/identity#logion-identity-agents-add)

## Rotate agent api key

```http
POST /v1/identity/users/{user_id}/agents/{agent_id}/api-keys
```

Operation id: `rotate_agent_api_key`

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `user_id` | path | string(uuid) | yes |
| `agent_id` | path | string(uuid) | yes |

**Request body**

Body `RotateAgentApiKeyRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `user_password` | string | yes | min length 8; max length 255 |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful response | `RotateAgentApiKeyResponse` |
| `401` | Unauthorized | `ErrorResponse` |
| `404` | Not found | `ErrorResponse` |
| `409` | Conflict | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |
| `429` | Too many requests | `ErrorResponse` |

Returns `RotateAgentApiKeyResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent` | AgentResponse | yes |  |
| `api_key` | string | yes |  |
| `api_key_prefix` | string | yes |  |

**From the CLI**

- [`logion identity agents-rotate-key`](/docs/cli/identity#logion-identity-agents-rotate-key)