Skip to main content

Identity and sign-in

These routes are behind Identity & SSO in the console. They take a Keycloak access token. Orchestrate configures Keycloak through its admin API, so nothing here needs Keycloak's own admin console. See Identity and single sign-on.

Identity providers​

Platform admin only.

Method and pathWhat it does
GET /identity/providersThe providers, with their group mappings.
GET /identity/providers/{alias}One provider, and the values to register at the provider.
POST /identity/providersAdd a provider. See below.
PUT /identity/providers/{alias}Replace a provider's settings.
PATCH /identity/providers/{alias}{"enabled": true} or false.
DELETE /identity/providers/{alias}Remove a provider.

A provider has an alias, a display_name (the sign-in button), a type (oidc or saml), enabled, hide_on_login, trust_email, sync_mode, object_id_claim (for Microsoft Teams), group_mappings, and one of:

TypeSettings
oidcdiscovery_url, or issuer, authorization_url, token_url, jwks_url, userinfo_url and logout_url; client_id, client_secret, client_auth, scopes, pkce
samlmetadata_url or metadata_xml, or idp_entity_id, sso_url, slo_url and signing_certificate; name_id_format, principal_type, principal_attribute, email_attribute, first_name_attribute, last_name_attribute, want_assertions_signed, validate_signature, sign_requests

A group mapping is {"claim", "value", "group", "regex"}: when the claim (or SAML attribute) has the value, the user is in the group. The client secret is stored in Keycloak's vault, never in a database, and never returned.

Groups and bindings​

Method and pathWhoWhat it does
GET /identity/groupsplatform adminThe groups.
POST /identity/groupsplatform admin{"name", "parent_path"}.
DELETE /identity/groups/{group_id}platform adminRemove a group.
GET /identity/groups/{group_id}/membersplatform adminIts members.
PUT, DELETE /identity/groups/{group_id}/members/{user_sub}platform adminAdd or remove a member.
GET /identity/group-bindingsorganization admin or platform adminBindings, optionally for one tenant_id.
POST /identity/group-bindingsorganization admin for their own organization, or platform admin{"group_path", "scope", "scope_id", "role"}: scope is tenant, folder or project, and role is viewer, developer or admin.
DELETE /identity/group-bindings/{binding_id}the sameRemove a binding.

Two-factor sign-in​

Method and pathWhoWhat it does
GET /identity/securityplatform adminThe realm's MFA and password-reset settings.
PUT /identity/securityplatform admin{"mfa_required", "apply_to_existing_users", "reset_password_allowed"}.
PUT /tenants/{tenant_id}/securityorganization admin{"mfa_required": true} for the organization's members.
GET /me/securityany signed-in userWhether you need to set up an authenticator. Works even while MFA blocks your other calls.

Directory and invitations​

Method and pathWhoWhat it does
GET /directory/users?q=anyone who can manage members somewhereSearch users by name or email.
POST /directory/invitesorganization admin or platform admin{"email", "first_name", "last_name", "delivery", "tenant_id", "role"}. delivery is auto, email or link. A link invitation returns a one-time link that expires after 72 hours. email without SMTP answers 409.
GET /directory/linkssigned-in userOpen invitation and reset links: all of them for a platform admin, your own otherwise.
DELETE /directory/links/{link_id}the link's creator or a platform adminRevoke a link.
POST /directory/users/{user_sub}/password-resetplatform admin{"delivery"}: a reset email or a one-time link for a local user, valid 24 hours.
POST /account-links/lookup, POST /account-links/redeemthe link's tokenUsed by the set-password page. The token is the credential.
Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →