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 and 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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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_ |
422 |
application/json → 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
Responses:
| Status | Body |
|---|---|
201 |
application/json → ApiResponse_IdPResponse_ |
422 |
application/json → 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 |
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_ |
422 |
application/json → 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
Responses:
| Status | Body |
|---|---|
200 |
application/json → ApiResponse_IdPResponse_ |
422 |
application/json → 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__ |
422 |
application/json → 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
Responses:
| Status | Body |
|---|---|
201 |
application/json → ApiResponse_GroupMappingResponse_ |
422 |
application/json → 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 |
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_ |
422 |
application/json → 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 |
yes | |
meta |
MetaResponse |
no |
ApiResponse_IdPResponse_#
| Field | Type | Required | Description |
|---|---|---|---|
data |
IdPResponse |
yes | |
meta |
MetaResponse |
no |
ApiResponse_TestConnectionResponse_#
| Field | Type | Required | Description |
|---|---|---|---|
data |
TestConnectionResponse |
yes | |
meta |
MetaResponse |
no |
ApiResponse_list_GroupMappingResponse__#
| Field | Type | Required | Description |
|---|---|---|---|
data |
array of GroupMappingResponse |
yes | |
meta |
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 |
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 | null |
no | |
saml_config |
IdPSAMLConfig | null |
no | |
attribute_mapping |
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 | null |
no | |
saml_config |
IdPSAMLConfig | null |
no | |
attribute_mapping |
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 |
yes | |
pagination |
PaginationMeta |
yes | |
meta |
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 |