AimableDocs
DocsAPI ReferenceRelease Notes

Admin Identity Providers

Updated 9 July 2026

Identity Providers Management

The admin-identity-providers domain allows administrators to configure and manage external Identity Providers (IdP) for single sign-on (SSO). By integrating providers like Google or Microsoft, you can streamline user authentication across the Aimable Platform. This API enables you to create, validate, update, and remove identity configurations securely.

Key Concepts

  • Identity Provider Config: A configuration object defining how an external IdP connects to the platform. Each config is identified by a unique config_id.
  • Provider Type: Specifies the IdP technology. Supported values are google and microsoft.
  • Validation: Before activating a provider, you should validate the configuration to ensure credentials and discovery URLs are correct.

See Authentication & errors for request authentication and the standard error responses.

Common Workflows

  1. Create a new identity provider configuration.
  2. Validate the configuration to ensure connectivity.
  3. List providers to verify status.
  4. Update or Delete configurations as needed.

API Examples

Create an Identity Provider

Send a POST request to /api/v1/admin/identity-providers with the required provider details.

bash
curl -X POST "https://api.aimable.com/api/v1/admin/identity-providers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "google",
    "display_name": "Corporate Google SSO",
    "issuer": "https://accounts.google.com",
    "discovery_url": "https://accounts.google.com/.well-known/openid-configuration",
    "client_id": "1234567890-abcdef.apps.googleusercontent.com",
    "allowed_scopes": ["openid", "email", "profile"],
    "allowed_email_domains": ["example.com"],
    "require_email_verified": true
  }'
python
import requests
 
url = "https://api.aimable.com/api/v1/admin/identity-providers"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
payload = {
    "provider_type": "google",
    "display_name": "Corporate Google SSO",
    "issuer": "https://accounts.google.com",
    "discovery_url": "https://accounts.google.com/.well-known/openid-configuration",
    "client_id": "1234567890-abcdef.apps.googleusercontent.com",
    "allowed_scopes": ["openid", "email", "profile"],
    "allowed_email_domains": ["example.com"],
    "require_email_verified": True
}
 
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response (201): Returns the created configuration including the generated config_id.

Validate a Configuration

Before relying on a provider, validate it using the config_id returned during creation.

bash
curl -X POST "https://api.aimable.com/api/v1/admin/identity-providers/cfg_12345/validate" \
  -H "Authorization: Bearer <token>"

Response (200): Indicates the provider settings are reachable and valid.

List Identity Providers

Retrieve all configured providers. You can filter by status if needed.

bash
curl -X GET "https://api.aimable.com/api/v1/admin/identity-providers?status=active" \
  -H "Authorization: Bearer <token>"

Update and Delete

To modify settings, send a PATCH request to /api/v1/admin/identity-providers/{config_id}. Only include the fields you wish to change. To remove a provider entirely, send a DELETE request to the same path.

bash
curl -X PATCH "https://api.aimable.com/api/v1/admin/identity-providers/cfg_12345" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Updated Corporate SSO"
  }'

When creating or updating a provider, ensure provider_type matches supported values (google, microsoft) and required fields like client_id and discovery_url are present.

Related Endpoints

See also