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

# SSO API

> OIDC sign-in, CLI device sign-in, and SSO settings: the organization and SSO features.

> [!NOTE]
>
> **Plans:** Pro and Enterprise. **Self-hosted:** Enterprise license.

On Nasiko Cloud, the workspace owner connects an identity provider from **Settings → Security → Single sign-on**; Free and Individual are refused. On a self-hosted open-source server, the routes on this page return `404`.

Behavioral guide: [SSO and SCIM](https://docs.nasiko.com/governance/sso-and-scim.md).

| Method | Path | Who |
| - | - | - |
| `GET` | `/api/auth/oidc/status` | Anyone, no sign-in |
| `GET` | `/api/auth/oidc/login` | Anyone, no sign-in (browser) |
| `GET` | `/api/auth/oidc/callback` | Your identity provider redirects the browser here |
| `POST` | `/api/auth/device/code` | Anyone, no sign-in (CLI) |
| `POST` | `/api/auth/device/token` | Anyone holding a device code (CLI) |
| `GET` `POST` | `/device` | Signed-in browser |
| `GET` | `/api/settings/oidc` | `admin` role or superuser |
| `PUT` | `/api/settings/oidc` | `admin` role or superuser |

Routes that need a sign-in take the session token as `Authorization: Bearer <token>` or the dashboard session cookie. A missing or invalid token returns `401`:

```json theme={null}
{ "data": null, "status_code": 401, "message": "missing or invalid token" }
```

## SSO status

`GET /api/auth/oidc/status`

Whether SSO is configured, and for which kind of provider. The sign-in page and `nasiko auth login` call it to decide whether to offer SSO. No sign-in needed.

```bash theme={null}
curl https://<your-host>/api/auth/oidc/status
```

```json theme={null}
{ "configured": true, "provider": "microsoft" }
```

| Field | Type | Description |
| - | - | - |
| `configured` | boolean | `true` when an issuer, client ID, client secret, and redirect URI are all set |
| `provider` | string \| null | `microsoft` (Entra ID), `okta`, `google`, `keycloak`, `aws`, or `generic`. `null` when not configured |

Always `200`.

## Browser sign-in

`GET /api/auth/oidc/login`

Starts a sign-in. Redirects the browser to your identity provider's consent screen. Open it in a browser, not with an API client.

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `redirect` | string | No | Where to land after sign-in. A path on this server (starting with `/`), or an absolute URL whose origin is listed in `OIDC_ALLOWED_REDIRECT_ORIGINS`. Anything else is ignored. Default: the dashboard root |

| Status | Meaning |
| - | - |
| `307` | Redirect to your identity provider |
| `503` | SSO isn't configured. Body: `OIDC SSO not configured` |
| `502` | Nasiko couldn't reach your identity provider's discovery document |

`GET /api/auth/oidc/callback`

Your identity provider sends the browser here with `code` and `state`. Nasiko checks the state, PKCE verifier, and nonce, verifies the ID token, creates or updates the user, places them in org units from their groups, and starts a session. Then it returns the browser to the `redirect` target. For a same-origin target, the session is set as a cookie. For a cross-origin target, the token and its lifetime are appended as `#token=<token>&expires_in=<seconds>`.

If the sign-in fails, the browser returns to the target with `#error=<code>`:

| Code | Meaning |
| - | - |
| `denied` | The user or the provider declined |
| `missing_code` | The provider returned no authorization code |
| `state_mismatch`, `state_replayed`, `state_check_unavailable` | The sign-in request didn't match, was already used, or couldn't be checked. Start again |
| `missing_pkce`, `missing_nonce` | The sign-in cookies were lost between the two redirects. Start again in the same browser |
| `exchange_failed` | The provider rejected the code exchange. Check the client secret and redirect URI |
| `token_verification_failed` | The ID token didn't verify |
| `personal_email_not_allowed` | A personal email address isn't allowed on this deployment |
| `account_deactivated` | The matching Nasiko user is deactivated |
| `not_invited` | `SSO_MEMBERS_ONLY` is on and no matching user exists |
| `user_save_failed`, `internal_error` | Nasiko couldn't save the user. Retry, then contact your operator |

If SSO isn't configured, the callback returns `503`.

## CLI sign-in (device code)

The [OAuth 2.0 device authorization grant](https://www.rfc-editor.org/rfc/rfc8628). `nasiko auth login --sso` and `nasiko-ee auth login --sso` use it. Sessions issued this way are ordinary sessions: they appear and can be revoked like browser sessions.

### Request a code

`POST /api/auth/device/code`

No body. No sign-in.

```bash theme={null}
curl -X POST https://<your-host>/api/auth/device/code
```

```json theme={null}
{
  "device_code": "8Jx2...",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://<your-host>/device",
  "verification_uri_complete": "https://<your-host>/device?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}
```

| Field | Type | Description |
| - | - | - |
| `device_code` | string | Secret. Send it to the token route. Never show it to the user |
| `user_code` | string | Eight characters in two groups of four. Show it to the user |
| `verification_uri` | string | Page where the user enters the code |
| `verification_uri_complete` | string | The same page with the code filled in |
| `expires_in` | integer | Seconds until the code expires (600) |
| `interval` | integer | Minimum seconds between polls (5) |

Returns `503` if the server can't record the request.

### Approve in the browser

`GET /device` shows the approval page. Without a session, it sends the browser through SSO sign-in first and comes back. With `?user_code=` it shows the code to confirm. The page posts the decision to `POST /device` as a form (`user_code`, `action=approve` or anything else to deny). The first decision wins.

### Poll for the session

`POST /api/auth/device/token`

| Body field | Type | Required | Description |
| - | - | - | - |
| `device_code` | string | Yes | From the code response |

```bash theme={null}
curl -X POST https://<your-host>/api/auth/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "8Jx2..."}'
```

On approval, `200`:

```json theme={null}
{ "access_token": "eyJhbGciOi...", "token_type": "Bearer" }
```

Until then, `400` with an `error` code, as the device grant specifies:

| `error` | Meaning | What to do |
| - | - | - |
| `authorization_pending` | Not approved yet | Poll again after `interval` seconds |
| `slow_down` | Polled sooner than `interval` | Add 5 seconds to your interval |
| `access_denied` | Denied in the browser, or the approver can no longer sign in | Stop |
| `expired_token` | The code expired or never existed | Request a new code |
| `invalid_grant` | The code already produced a session | Stop. Each code yields one session |

`503` means the session store is unavailable. Retry later.

## SSO settings

### Read the configuration

`GET /api/settings/oidc`

```bash theme={null}
curl https://<your-host>/api/settings/oidc \
  -H "Authorization: Bearer <admin-token>"
```

```json theme={null}
{
  "oidc_issuer_url": "https://login.microsoftonline.com/<tenant-id>/v2.0",
  "oidc_client_id": "0c1f...",
  "oidc_redirect_uri": "https://<your-host>/api/auth/oidc/callback",
  "oidc_scopes": "openid profile email",
  "oidc_provider_label": "entra",
  "oidc_client_secret_configured": true,
  "provider_kind": "entra",
  "provider_locked": true,
  "oidc_configured": true,
  "scim_enabled": true,
  "directory_sync_enabled": true
}
```

| Field | Type | Description |
| - | - | - |
| `oidc_issuer_url` | string \| null | Issuer URL |
| `oidc_client_id` | string \| null | Client ID |
| `oidc_redirect_uri` | string \| null | Redirect URI registered with your provider |
| `oidc_scopes` | string \| null | Space-separated scopes |
| `oidc_provider_label` | string \| null | The label users and units from this provider are filed under |
| `oidc_client_secret_configured` | boolean | Whether a secret is stored. The secret itself is never returned |
| `provider_kind` | string \| null | `entra`, `okta`, `google`, `keycloak`, `aws_iam_ic`, or `generic` |
| `provider_locked` | boolean | `true` once SSO is fully configured. Changing `provider_kind` then needs `allow_provider_switch` |
| `oidc_configured` | boolean | Issuer, client ID, and secret are all set |
| `scim_enabled` | boolean | SCIM provisioning is available (same as `oidc_configured`) |
| `directory_sync_enabled` | boolean | Directory sync is available: SSO is configured and the provider is Entra ID |

With nothing configured, every string field is `null` and every boolean `false`.

| Status | Meaning |
| - | - |
| `200` | The configuration |
| `403` | `{"error": "requires admin role"}` |

### Save the configuration

`PUT /api/settings/oidc`

Writes the issuer URL, client ID, redirect URI, and scopes exactly as sent: a field you leave out is saved as `null`. Read the current values first and send them back with your change. The client secret is the exception. When the result is a complete configuration, Nasiko starts a directory sync in the background.

| Body field | Type | Required | Description |
| - | - | - | - |
| `oidc_issuer_url` | string | No | Issuer URL |
| `oidc_client_id` | string | No | Client ID |
| `oidc_redirect_uri` | string | No | Must match the redirect URI registered with your provider exactly |
| `oidc_scopes` | string | No | Space-separated. The sign-in flow uses `openid profile email` when unset |
| `oidc_client_secret` | string | No | Write-only. Leave it out to keep the stored secret. `""` clears it. Any other value replaces it and is encrypted at rest |
| `provider_kind` | string | No | `entra`, `okta`, `google`, `keycloak`, `aws_iam_ic`, or `generic`. Left out, it's taken from `oidc_provider_label` or detected from the issuer URL |
| `oidc_provider_label` | string | No | Pin the label explicitly. Usually leave it out |
| `allow_provider_switch` | boolean | No | Default `false`. Set `true` to change the provider on a locked configuration. Users and units filed under the old provider aren't matched to the new one |

Unknown fields are rejected.

```bash theme={null}
curl -X PUT https://<your-host>/api/settings/oidc \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_kind": "okta",
    "oidc_issuer_url": "https://acme.okta.com",
    "oidc_client_id": "0oa1...",
    "oidc_client_secret": "<client-secret>",
    "oidc_redirect_uri": "https://<your-host>/api/auth/oidc/callback",
    "oidc_scopes": "openid profile email"
  }'
```

Returns the saved configuration:

```json theme={null}
{
  "oidc_issuer_url": "https://acme.okta.com",
  "oidc_client_id": "0oa1...",
  "oidc_redirect_uri": "https://<your-host>/api/auth/oidc/callback",
  "oidc_scopes": "openid profile email",
  "oidc_provider_label": "okta",
  "oidc_client_secret_configured": true
}
```

To turn SSO off, clear every field and allow a later provider switch:

```json theme={null}
{
  "oidc_issuer_url": "",
  "oidc_client_id": "",
  "oidc_client_secret": "",
  "oidc_redirect_uri": "",
  "oidc_scopes": "",
  "allow_provider_switch": true
}
```

On a self-hosted server, also unset the `OIDC_*` environment variables. With no stored configuration, the server falls back to them.

| Status | Meaning |
| - | - |
| `200` | Saved |
| `400` | Unknown `provider_kind`. Plain-text body naming the allowed values |
| `403` | `{"error": "requires admin role"}` |
| `409` | SSO is configured for another provider. Plain-text body. Resend with `"allow_provider_switch": true` if you mean it |
| `422` | The body has an unknown field or a wrong type |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.