SSO API
13 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.
Endpoints
GET /api/v1/admin/sso-providers
List SSO providers
List all SSO providers (admin only)
Responses
| Status | Description | Body |
|---|---|---|
200 | List of SSO providers | application/json: object |
403 | Admin access required | - |
Fields of the 200 response (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
providers | array of SSOProvider | yes | - |
POST /api/v1/admin/sso-providers
Create SSO provider
Create a new SSO provider (admin only)
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
config | object | no | - |
display_name | string | yes | - |
enabled | boolean | no | - |
kind | string | yes | One of: oidc, saml. |
slug | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
201 | SSO provider created | application/json: SSOProvider |
400 | Invalid request | application/json: Error |
403 | Admin access required | - |
GET /api/v1/admin/sso-providers/{slug}
Get SSO provider
Get details of a specific SSO provider (admin only)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | SSO provider details | application/json: SSOProvider |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | SSO provider not found | - |
PATCH /api/v1/admin/sso-providers/{slug}
Update SSO provider
Update an SSO provider (admin only)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
config | object | no | - |
display_name | string | no | - |
enabled | boolean | no | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | SSO provider updated | application/json: SSOProvider |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | SSO provider not found | - |
DELETE /api/v1/admin/sso-providers/{slug}
Delete SSO provider
Delete an SSO provider (admin only)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
204 | SSO provider deleted | - |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | SSO provider not found | - |
POST /api/v1/admin/sso-providers/{slug}/test
Test SSO provider
Test an SSO provider configuration (admin only)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Test result | application/json: object |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
404 | SSO provider not found | - |
Fields of the 200 response (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
error | string | no | - |
kind | string | no | - |
message | string | no | - |
ok | boolean | no | - |
GET /api/v1/auth/sso/oidc/{slug}/callback
OIDC callback
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
code | query | string | no | - |
state | query | string | no | - |
Responses
| Status | Description | Body |
|---|---|---|
302 | 302 | - |
default | Error | application/json: Error |
GET /api/v1/auth/sso/oidc/{slug}/login
Begin OIDC login
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
302 | 302 | - |
default | Error | application/json: Error |
POST /api/v1/auth/sso/oidc/{slug}/logout
OIDC logout
Ends the local session (the request body is ignored; same-origin only). When the session was created by this provider and its IdP advertises an end_session_endpoint, responds 200 with the RP-initiated logout URL the browser must navigate to; otherwise 204.
Authentication: none (public endpoint).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Logged out locally; continue at the IdP | application/json: EndSessionResponse |
204 | Logged out locally, no IdP logout | - |
default | Error | application/json: Error |
GET /api/v1/auth/sso/providers
List SSO providers
List available SSO providers (public)
Authentication: none (public endpoint).
Responses
| Status | Description | Body |
|---|---|---|
200 | List of SSO providers | application/json: object |
Fields of the 200 response (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
providers | array of object | yes | - |
providers[].display_name | string | no | - |
providers[].kind | string | no | One of: oidc, saml. |
providers[].slug | string | no | - |
POST /api/v1/auth/sso/saml/{slug}/acs
SAML assertion consumer service
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
302 | 302 | - |
default | Error | application/json: Error |
GET /api/v1/auth/sso/saml/{slug}/login
Begin SAML login
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
302 | 302 | - |
default | Error | application/json: Error |
GET /api/v1/auth/sso/saml/{slug}/metadata
SAML SP metadata
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Success | - |
default | Error | application/json: Error |