---
title: Identity Providers API
path: reference/api/identity-providers
status: published
---

# Identity Providers API

Reference for the `Identity Providers` endpoint group — 18 endpoints.

Generated from the live OpenAPI spec. Re-run `_generate_api_reference.py` after backend changes.

## Authentication

All endpoints require a Bearer JWT in the `Authorization` header unless noted otherwise. See [Concepts → Tokens and scopes](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/reference/oauth-endpoints) for how to obtain one.

## Endpoints

### **GET** `/api/v1/admin/identity-providers/`

_List Identity Providers_

List identity providers with filtering.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `tenant_id` | query | no | `string` \| `null` |  |
| `provider_type` | query | no | `string` \| `null` |  |
| `search` | query | no | `string` \| `null` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/admin/identity-providers/`

_Create Identity Provider_

Create a new identity provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → object

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/admin/identity-providers/{idp_id}`

_Delete Identity Provider_

Soft delete an identity provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `idp_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/identity-providers/{idp_id}`

_Get Identity Provider_

Get an identity provider by ID.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `idp_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **PATCH** `/api/v1/admin/identity-providers/{idp_id}`

_Update Identity Provider_

Update an identity provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `idp_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → object

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/admin/identity-providers/{idp_id}/sync`

_Sync Identity Provider_

Synchronize users from an LDAP identity provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `idp_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/identity-providers/{idp_id}/sync-logs`

_List Sync Logs_

List sync logs for an identity provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `idp_id` | path | yes | `string` |  |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/identity-providers/{idp_id}/sync-logs/{log_id}`

_Get Sync Log_

Get a sync log with its details.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `idp_id` | path | yes | `string` |  |
| `log_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/admin/identity-providers/{idp_id}/test`

_Test Identity Provider_

Test connectivity to an identity provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `idp_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/identity-providers/`

_List Identity Providers_

List Identity Providers for a tenant.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `enabled_only` | query | no | `boolean` | Only return enabled IdPs |
| `protocol` | query | no | `string` \| `null` | Filter by protocol (OIDC, SAML) |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`PaginatedResponse_IdPListItem_`](#schema-paginatedresponse-idplistitem) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/tenants/{tenant_id}/identity-providers/`

_Create Identity Provider_

Create a new Identity Provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`IdPCreate`](#schema-idpcreate)

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → [`ApiResponse_IdPResponse_`](#schema-apiresponse-idpresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/tenants/{tenant_id}/identity-providers/{idp_id}`

_Delete Identity Provider_

Delete an Identity Provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `idp_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/identity-providers/{idp_id}`

_Get Identity Provider_

Get Identity Provider details.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `idp_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_IdPResponse_`](#schema-apiresponse-idpresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **PATCH** `/api/v1/tenants/{tenant_id}/identity-providers/{idp_id}`

_Update Identity Provider_

Update an Identity Provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `idp_id` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`IdPUpdate`](#schema-idpupdate)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_IdPResponse_`](#schema-apiresponse-idpresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/identity-providers/{idp_id}/group-mappings`

_List Group Mappings_

List group mappings for an Identity Provider.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `idp_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_list_GroupMappingResponse__`](#schema-apiresponse-list-groupmappingresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/tenants/{tenant_id}/identity-providers/{idp_id}/group-mappings`

_Create Group Mapping_

Create a group mapping.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `idp_id` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`GroupMappingCreate`](#schema-groupmappingcreate)

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → [`ApiResponse_GroupMappingResponse_`](#schema-apiresponse-groupmappingresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/tenants/{tenant_id}/identity-providers/{idp_id}/group-mappings/{mapping_id}`

_Delete Group Mapping_

Delete a group mapping.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `idp_id` | path | yes | `string` |  |
| `mapping_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/tenants/{tenant_id}/identity-providers/{idp_id}/test`

_Test Connection_

Test connection to an Identity Provider.

For OIDC: Fetches the discovery document and validates configuration.
For SAML: Validates the IdP metadata and certificate.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `idp_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_TestConnectionResponse_`](#schema-apiresponse-testconnectionresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

## Schemas

Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.

### `ApiResponse_GroupMappingResponse_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`GroupMappingResponse`](#schema-groupmappingresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `ApiResponse_IdPResponse_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`IdPResponse`](#schema-idpresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `ApiResponse_TestConnectionResponse_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`TestConnectionResponse`](#schema-testconnectionresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `ApiResponse_list_GroupMappingResponse__`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array of [`GroupMappingResponse`](#schema-groupmappingresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `GroupMappingCreate`

Request to create a group mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `external_group_id` | `string` | yes |  |
| `external_group_name` | `string` \| `null` | no |  |
| `internal_group_id` | `string` | yes |  |

### `GroupMappingResponse`

Group mapping response.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `idp_id` | `string` | yes |  |
| `external_group_id` | `string` | yes |  |
| `external_group_name` | `string` \| `null` | yes |  |
| `internal_group_id` | `string` | yes |  |
| `internal_group_name` | `string` \| `null` | no |  |
| `created_at` | `string` (`date-time`) | yes |  |

### `HTTPValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `detail` | array of [`ValidationError`](#schema-validationerror) | no |  |

### `IdPAttributeMapping`

Attribute mapping from IdP claims to ScaiKey user fields.

| Field | Type | Required | Description |
|---|---|---|---|
| `email` | `string` | no | Default: `email` |
| `first_name` | `string` | no | Default: `given_name` |
| `last_name` | `string` | no | Default: `family_name` |
| `display_name` | `string` \| `null` | no | Default: `name` |
| `groups` | `string` \| `null` | no | Default: `groups` |

### `IdPCreate`

Request to create an Identity Provider.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes |  |
| `display_name` | `string` \| `null` | no |  |
| `protocol` | `string` | yes | OIDC or SAML |
| `enabled` | `boolean` | no | Default: `True` |
| `auto_create_users` | `boolean` | no | Default: `True` |
| `update_user_on_login` | `boolean` | no | Default: `True` |
| `oidc_config` | [`IdPOIDCConfig`](#schema-idpoidcconfig) \| `null` | no |  |
| `saml_config` | [`IdPSAMLConfig`](#schema-idpsamlconfig) \| `null` | no |  |
| `attribute_mapping` | [`IdPAttributeMapping`](#schema-idpattributemapping) \| `null` | no |  |
| `allowed_domains` | array of `string` \| `null` | no |  |

### `IdPListItem`

Identity Provider list item.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `name` | `string` | yes |  |
| `display_name` | `string` \| `null` | yes |  |
| `protocol` | `string` | yes |  |
| `enabled` | `boolean` | yes |  |
| `created_at` | `string` (`date-time`) | yes |  |

### `IdPOIDCConfig`

OIDC Identity Provider configuration.

| Field | Type | Required | Description |
|---|---|---|---|
| `issuer` | `string` | yes |  |
| `client_id` | `string` | yes |  |
| `client_secret` | `string` \| `null` | no |  |
| `authorization_endpoint` | `string` \| `null` | no |  |
| `token_endpoint` | `string` \| `null` | no |  |
| `userinfo_endpoint` | `string` \| `null` | no |  |
| `jwks_uri` | `string` \| `null` | no |  |
| `scopes` | array of `string` | no | Default: `['openid', 'profile', 'email']` |

### `IdPResponse`

Identity Provider response.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `tenant_id` | `string` | yes |  |
| `name` | `string` | yes |  |
| `display_name` | `string` \| `null` | yes |  |
| `protocol` | `string` | yes |  |
| `enabled` | `boolean` | yes |  |
| `auto_create_users` | `boolean` | yes |  |
| `update_user_on_login` | `boolean` | yes |  |
| `oidc_config` | object \| `null` | no |  |
| `saml_config` | object \| `null` | no |  |
| `attribute_mapping` | object \| `null` | no |  |
| `allowed_domains` | array of `string` \| `null` | no |  |
| `created_at` | `string` (`date-time`) | yes |  |
| `updated_at` | `string` (`date-time`) \| `null` | yes |  |

### `IdPSAMLConfig`

SAML Identity Provider configuration.

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | yes |  |
| `sso_url` | `string` | yes |  |
| `slo_url` | `string` \| `null` | no |  |
| `certificate` | `string` | yes |  |
| `sign_requests` | `boolean` | no | Default: `True` |
| `want_assertions_signed` | `boolean` | no | Default: `True` |
| `name_id_format` | `string` | no | Default: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` |

### `IdPUpdate`

Request to update an Identity Provider.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` \| `null` | no |  |
| `display_name` | `string` \| `null` | no |  |
| `enabled` | `boolean` \| `null` | no |  |
| `auto_create_users` | `boolean` \| `null` | no |  |
| `update_user_on_login` | `boolean` \| `null` | no |  |
| `oidc_config` | [`IdPOIDCConfig`](#schema-idpoidcconfig) \| `null` | no |  |
| `saml_config` | [`IdPSAMLConfig`](#schema-idpsamlconfig) \| `null` | no |  |
| `attribute_mapping` | [`IdPAttributeMapping`](#schema-idpattributemapping) \| `null` | no |  |
| `allowed_domains` | array of `string` \| `null` | no |  |

### `MetaResponse`

Metadata included in API responses.

| Field | Type | Required | Description |
|---|---|---|---|
| `request_id` | `string` \| `null` | no |  |
| `timestamp` | `string` (`date-time`) | no |  |

### `PaginatedResponse_IdPListItem_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array of [`IdPListItem`](#schema-idplistitem) | yes |  |
| `pagination` | [`PaginationMeta`](#schema-paginationmeta) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `PaginationMeta`

Pagination metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | `integer` | yes |  |
| `per_page` | `integer` | yes |  |
| `total_items` | `integer` | yes |  |
| `total_pages` | `integer` | yes |  |

### `TestConnectionResponse`

Test connection result.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | yes |  |
| `message` | `string` | yes |  |
| `details` | object \| `null` | no |  |

### `ValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `loc` | array of `string` \| `integer` | yes |  |
| `msg` | `string` | yes |  |
| `type` | `string` | yes |  |