> ## Documentation Index
> Fetch the complete documentation index at: https://build.onswig.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity API

The Identity API starts login flows, completes OTP/passkey flows, manages role
and invite operations, and reads identity policies through API-key guarded
runtime endpoints.

## Auth

Use an API key:

```text theme={null}
Authorization: Bearer sk_your_api_key
```

Some identity flows may return or consume flow-specific tokens after the
API-key-guarded start point. Developer-portal admin endpoints are intentionally
omitted from this reference.

## Start OAuth auth

`GET /identity/api/auth/start`

Query parameters:

| Parameter       | Type    | Description                              |
| :-------------- | :------ | :--------------------------------------- |
| `provider`      | string  | Provider key                             |
| `client_id`     | string  | Identity client id                       |
| `redirect_uri`  | string  | Redirect URI registered for the client   |
| `state`         | string  | Client state returned with the redirect  |
| `network`       | enum    | `NETWORK_DEVNET` or `NETWORK_MAINNET`    |
| `flow`          | string  | Flow name such as `role` or `session`    |
| `policy_id`     | string  | Policy used for signup/session flow      |
| `skip_approval` | boolean | Skip approval when allowed               |
| `invite_token`  | string  | Invite token for invite acceptance flows |

Response:

```json theme={null}
{
  "redirectUrl": "https://provider.example/authorize?...",
  "state": "client_state",
  "startToken": "start_token"
}
```

## Start email OTP

`POST /identity/api/auth/email/start`

```json theme={null}
{
  "provider": "email",
  "clientId": "client_123",
  "redirectUri": "https://app.example/callback",
  "state": "client_state",
  "network": "NETWORK_DEVNET",
  "flow": "session",
  "policyId": "policy_123",
  "email": "user@example.com"
}
```

The response includes `challengeId`, `maskedEmail`, `expiresAt`,
`otpEntryUrl`, and `startToken`.

## Start passkey challenge

`POST /identity/api/auth/passkey/start`

```json theme={null}
{
  "clientId": "client_123",
  "redirectUri": "https://app.example/callback",
  "network": "NETWORK_DEVNET",
  "ceremony": "PASSKEY_CEREMONY_REGISTRATION",
  "clientState": "state",
  "policyId": "policy_123"
}
```

The response returns a `challengeId` and `webauthnOptionsJson` for
`navigator.credentials`.

Identity client and organization-provider configuration is handled through
developer-portal admin surfaces, not API-key runtime endpoints.