Federation API
Reference for the Federation endpoint group — 12 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/auth/tenants/{tenant_slug}/federation/idps#
List Available Idps
List available external Identity Providers for login.
Returns IdPs that users can use to authenticate. This is used by the login page to show SSO buttons.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/federation/idps#
List Available Idps
List available external Identity Providers for login.
Returns IdPs that users can use to authenticate. This is used by the login page to show SSO buttons.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/federation/oidc/callback#
Oidc Callback
OIDC callback endpoint.
Receives the authorization code from the external IdP after user authentication, exchanges it for tokens, and creates/updates the local user account.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
|
code |
query | no | string | null |
|
state |
query | no | string | null |
|
error |
query | no | string | null |
|
error_description |
query | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/federation/oidc/callback#
Oidc Callback
OIDC callback endpoint.
Receives the authorization code from the external IdP after user authentication, exchanges it for tokens, and creates/updates the local user account.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
|
code |
query | no | string | null |
|
state |
query | no | string | null |
|
error |
query | no | string | null |
|
error_description |
query | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/federation/oidc/{idp_id}/authorize#
Oidc Authorize
Initiate OIDC authentication with an external IdP.
This endpoint is called when a user clicks "Sign in with {IdP}" on the login page. It redirects the user to the external IdP for authentication.
The original OAuth parameters are stored in state so they can be restored after the user returns from the IdP.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
|
idp_id |
path | yes | string |
|
response_type |
query | no | string | null |
|
client_id |
query | no | string | null |
|
redirect_uri |
query | no | string | null |
|
scope |
query | no | string | null |
|
state |
query | no | string | null |
|
nonce |
query | no | string | null |
|
code_challenge |
query | no | string | null |
|
code_challenge_method |
query | no | string | null |
|
login_hint |
query | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/federation/oidc/{idp_id}/authorize#
Oidc Authorize
Initiate OIDC authentication with an external IdP.
This endpoint is called when a user clicks "Sign in with {IdP}" on the login page. It redirects the user to the external IdP for authentication.
The original OAuth parameters are stored in state so they can be restored after the user returns from the IdP.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
|
idp_id |
path | yes | string |
|
response_type |
query | no | string | null |
|
client_id |
query | no | string | null |
|
redirect_uri |
query | no | string | null |
|
scope |
query | no | string | null |
|
state |
query | no | string | null |
|
nonce |
query | no | string | null |
|
code_challenge |
query | no | string | null |
|
code_challenge_method |
query | no | string | null |
|
login_hint |
query | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/federation/saml/acs#
Saml Acs
SAML Assertion Consumer Service (ACS) endpoint.
Receives the SAML Response from the IdP after user authentication.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/x-www-form-urlencoded→Body_saml_acs_api_v1_auth_tenants__tenant_slug__federation_saml_acs_post
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/federation/saml/acs#
Saml Acs
SAML Assertion Consumer Service (ACS) endpoint.
Receives the SAML Response from the IdP after user authentication.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/x-www-form-urlencoded→Body_saml_acs_api_v1_auth_tenants__tenant_slug__federation_saml_acs_post
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/federation/saml/metadata#
Saml Metadata
Return SAML SP metadata for the tenant.
External IdPs can use this to configure ScaiKey as a Service Provider.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/federation/saml/metadata#
Saml Metadata
Return SAML SP metadata for the tenant.
External IdPs can use this to configure ScaiKey as a Service Provider.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/federation/saml/{idp_id}/login#
Saml Login
Initiate SAML authentication with an external IdP.
Creates a SAML AuthnRequest and redirects the user to the IdP's SSO URL.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
|
idp_id |
path | yes | string |
|
response_type |
query | no | string | null |
|
client_id |
query | no | string | null |
|
redirect_uri |
query | no | string | null |
|
scope |
query | no | string | null |
|
state |
query | no | string | null |
|
nonce |
query | no | string | null |
|
code_challenge |
query | no | string | null |
|
code_challenge_method |
query | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/federation/saml/{idp_id}/login#
Saml Login
Initiate SAML authentication with an external IdP.
Creates a SAML AuthnRequest and redirects the user to the IdP's SSO URL.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
|
idp_id |
path | yes | string |
|
response_type |
query | no | string | null |
|
client_id |
query | no | string | null |
|
redirect_uri |
query | no | string | null |
|
scope |
query | no | string | null |
|
state |
query | no | string | null |
|
nonce |
query | no | string | null |
|
code_challenge |
query | no | string | null |
|
code_challenge_method |
query | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
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.
Body_saml_acs_api_v1_auth_tenants__tenant_slug__federation_saml_acs_post#
| Field | Type | Required | Description |
|---|---|---|---|
SAMLResponse |
string |
yes | |
RelayState |
string |
no |
HTTPValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
detail |
array of ValidationError |
no |
ValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
loc |
array of string | integer |
yes | |
msg |
string |
yes | |
type |
string |
yes |