---
title: Federation API
path: reference/api/federation
status: published
---

# 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](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#schema-body-saml-acs-api-v1-auth-tenants-tenant-slug-federation-saml-acs-post)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-body-saml-acs-api-v1-auth-tenants-tenant-slug-federation-saml-acs-post)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-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`](#schema-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`](#schema-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`](#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.

### `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`](#schema-validationerror) | no |  |

### `ValidationError`

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