IdP Configuration API Reference¶

Complete API reference for Partner Identity Provider (IdP) configuration endpoints. These endpoints allow partners to configure OIDC-based single sign-on for their users.

API Overview¶

The IdP Configuration API is part of the Partner Admin API and requires API key authentication. Each partner app can have one IdP configuration for OIDC-based SSO.

Base URL¶

Authentication¶

All IdP configuration endpoints require authentication using your Partner API Key and Client ID:

const headers = {
  'X-API-Key': process.env.CONTIO_API_KEY,
  'X-Client-ID': process.env.CONTIO_CLIENT_ID,
  'Content-Type': 'application/json'
};

Rate Limits¶

Admin API endpoints are rate-limited to 500 requests per 5 minutes (approximately 100 requests per minute). When you exceed the rate limit, the API returns a 429 Too Many Requests response.

Endpoints¶

Create IdP Configuration¶

Creates a new OIDC identity provider configuration for the authenticated partner app.

Endpoint: POST /v1/partner/admin/idp

Request Body:

{
  "name": "Acme Corporate SSO",
  "discovery_url": "https://login.acme.com/.well-known/openid-configuration",
  "idp_client_id": "contio-integration-prod",
  "idp_client_secret": "secret-from-idp-admin-console",
  "scopes": ["openid", "email", "profile"],
  "claim_mappings": {
    "email": "email",
    "name": "name"
  },
  "mode": "strict",
  "allowed_email_domains": ["acme.com", "acme.co.uk"]
}

Request Fields:

Response (201 Created):

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "partner_app_id": "98765432-10ab-cdef-0123-456789abcdef",
  "name": "Acme Corporate SSO",
  "type": "oidc",
  "discovery_url": "https://login.acme.com/.well-known/openid-configuration",
  "idp_client_id": "contio-integration-prod",
  "scopes": ["openid", "email", "profile"],
  "claim_mappings": {
    "email": "email",
    "name": "name"
  },
  "mode": "strict",
  "allowed_email_domains": ["acme.com", "acme.co.uk"],
  "is_active": true,
  "issuer": "https://login.acme.com",
  "authorization_endpoint": "https://login.acme.com/oauth2/authorize",
  "token_endpoint": "https://login.acme.com/oauth2/token",
  "userinfo_endpoint": "https://login.acme.com/oauth2/userinfo",
  "jwks_uri": "https://login.acme.com/.well-known/jwks.json",
  "discovery_last_fetched_at": "2024-01-01T00:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Error Responses:

Example:

// Note: IdP configuration methods coming soon to SDK
// For now, use direct API calls:

const response = await fetch('https://api.contio.ai/v1/partner/admin/idp', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CONTIO_API_KEY,
    'X-Client-ID': process.env.CONTIO_CLIENT_ID,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Company SSO',
    discovery_url: 'https://company.okta.com/.well-known/openid-configuration',
    idp_client_id: '0oa1234567890abcdef',
    idp_client_secret: process.env.IDP_CLIENT_SECRET,
    mode: 'strict',
    allowed_email_domains: ['company.com']
  })
});

if (!response.ok) {
  const error = await response.json();
  console.error('Failed to create IdP config:', error.code, error.error);
  throw new Error(error.error);
}

const config = await response.json();
console.log('Created IdP config:', config.id);

Get IdP Configuration¶

Retrieves the current IdP configuration for the authenticated partner app.

Endpoint: GET /v1/partner/admin/idp

Response (200 OK):

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "partner_app_id": "98765432-10ab-cdef-0123-456789abcdef",
  "name": "Acme Corporate SSO",
  "type": "oidc",
  "discovery_url": "https://login.acme.com/.well-known/openid-configuration",
  "idp_client_id": "contio-integration-prod",
  "scopes": ["openid", "email", "profile"],
  "claim_mappings": {
    "email": "email",
    "name": "name"
  },
  "mode": "strict",
  "allowed_email_domains": ["acme.com", "acme.co.uk"],
  "is_active": true,
  "issuer": "https://login.acme.com",
  "authorization_endpoint": "https://login.acme.com/oauth2/authorize",
  "token_endpoint": "https://login.acme.com/oauth2/token",
  "userinfo_endpoint": "https://login.acme.com/oauth2/userinfo",
  "jwks_uri": "https://login.acme.com/.well-known/jwks.json",
  "discovery_last_fetched_at": "2024-01-01T00:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Error Responses:

Example:

const response = await fetch('https://api.contio.ai/v1/partner/admin/idp', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.CONTIO_API_KEY,
    'X-Client-ID': process.env.CONTIO_CLIENT_ID
  }
});

if (response.status === 404) {
  console.log('No IdP configuration found');
  return null;
}

const config = await response.json();
console.log('IdP config:', config.name, '- Active:', config.is_active);

Update IdP Configuration¶

Updates the IdP configuration for the authenticated partner app. All fields are optional; only include fields you want to change.

Endpoint: PUT /v1/partner/admin/idp

Request Body:

{
  "name": "Updated SSO Name",
  "discovery_url": "https://new-idp.acme.com/.well-known/openid-configuration",
  "idp_client_id": "new-client-id",
  "idp_client_secret": "new-client-secret",
  "scopes": ["openid", "email", "profile", "groups"],
  "claim_mappings": {
    "email": "email",
    "name": "displayName"
  },
  "mode": "partner_managed",
  "allowed_email_domains": ["acme.com", "subsidiary.com"],
  "is_active": true
}

Request Fields:

Response (200 OK):

Returns the updated IdP configuration (same schema as GET response).

Error Responses:

Example:

// Disable the IdP configuration temporarily
const response = await fetch('https://api.contio.ai/v1/partner/admin/idp', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.CONTIO_API_KEY,
    'X-Client-ID': process.env.CONTIO_CLIENT_ID,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    is_active: false
  })
});

const config = await response.json();
console.log('IdP config active:', config.is_active);

Delete IdP Configuration¶

Deletes the IdP configuration for the authenticated partner app. This action cannot be undone.

Endpoint: DELETE /v1/partner/admin/idp

Response (204 No Content):

No response body on success.

Error Responses:

Example:

const response = await fetch('https://api.contio.ai/v1/partner/admin/idp', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.CONTIO_API_KEY,
    'X-Client-ID': process.env.CONTIO_CLIENT_ID
  }
});

if (response.status === 204) {
  console.log('IdP configuration deleted successfully');
} else if (response.status === 404) {
  console.log('No IdP configuration to delete');
}

Data Schemas¶

IdPConfigResponse¶

The complete IdP configuration object returned by GET and POST/PUT endpoints.

ClaimMappings¶

The claim_mappings object maps Contio user fields to IdP claim names. This allows customization for IdPs that use non-standard claim names.

Standard OIDC Example:

{
  "email": "email",
  "name": "name"
}

Azure AD Example:

{
  "email": "preferred_username",
  "name": "name",
  "given_name": "given_name",
  "family_name": "family_name"
}

Custom IdP Example:

{
  "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
  "name": "displayName",
  "given_name": "firstName",
  "family_name": "lastName"
}

DomainValidationMode¶

The mode field controls how user email domains are validated during SSO.

ErrorResponse¶

All error responses follow this format:

{
  "code": "error_code",
  "error": "Human-readable error message",
  "request_id": "unique-request-id"
}

Error Reference¶

Complete list of error codes for IdP configuration endpoints.

Partner SSO Flow Endpoints¶

These public endpoints handle the SSO authentication flow. They are documented here for reference but are typically not called directly by partner applications.

Get Partner SSO Info¶

Returns partner branding and SSO configuration status for landing pages.

Endpoint: GET /v1/partner/sso/info/{slug}

Path Parameters:

Response (200 OK):

{
  "slug": "acme",
  "name": "Acme Inc",
  "co_brand_name": "Acme Meetings",
  "co_brand_logo_url": "https://cdn.acme.com/logo.png",
  "has_idp_config": true,
  "is_active": true
}

Rate Limit: 30 requests per minute per IP address.

Initiate SSO Flow¶

Starts the SSO authentication flow for a partner's identity provider.

Endpoint: GET /v1/partner/sso/initiate

Query Parameters:

Response (200 OK):

{
  "authorization_url": "https://login.acme.com/oauth2/authorize?...",
  "session_id": "sess_abc123"
}

Response (302 Found): When auto=true, redirects directly to the authorization URL.

SSO Callback¶

Handles the OIDC callback from the partner's identity provider. This endpoint is called by the IdP after user authentication.

Endpoint: GET /v1/partner/sso/callback

Query Parameters:

Response: Redirects to the target application (web or desktop deep link) after processing.

Session Status¶

Returns the current status of a partner SSO session for polling.

Endpoint: GET /v1/partner/sso/session/{session_id}

Response (200 OK):

{
  "status": "pending",
  "user_id": null,
  "target": "desktop",
  "error": null
}

Status Values:

SDK Support¶

When SDK support is available, the methods will follow this pattern:

// Future SDK usage (not yet available)
const { admin } = ContioPartnerSDK.forAdmin({
  apiKey: process.env.CONTIO_API_KEY,
  clientId: process.env.CONTIO_CLIENT_ID
});

// Create IdP configuration
const config = await admin.idp.create({
  name: 'Company SSO',
  discovery_url: 'https://company.okta.com/.well-known/openid-configuration',
  idp_client_id: 'client-id-from-your-idp',
  idp_client_secret: 'client-secret-from-your-idp',
  mode: 'strict',
  allowed_email_domains: ['company.com']
});

// Get IdP configuration
const config = await admin.idp.get();

// Update IdP configuration
const updated = await admin.idp.update({ is_active: false });

// Delete IdP configuration
await admin.idp.delete();

Next Steps¶

• SSO Integration Guide - Step-by-step integration walkthrough
• OAuth Flow Guide - Standard OAuth for user data access
• Authentication - Authentication overview
• Credential Management - API key rotation