IdRa

Admin and SCIM reference

The SCIM server and the part of IdRa's /api/admin that an integrator can use, with the authentication and permission each operation needs. Also available as an OpenAPI file.

This page and openapi-admin.json are generated from IdRa's routes. A test fails if a mounted route is neither listed here, in the API reference, nor under what's left out.

17 SCIM operations and 123 /api/admin operations are listed.

What this reference doesn't cover

  • Responses aren't described.
  • A write with no fields listed has no validated body, or checks it inside the handler. The JSON file has the full schemas.
  • /api/admin paths aren't versioned. They serve IdRa's console and change with it. /api/v1 is the surface built for compatibility.
  • Permissions are what the route's gate asks of the caller's role. Handlers can refuse further, for example an admin limited to certain groups or apps, or an action only super admins may take, and that isn't listed.
  • SCIM shapes follow RFC 7643. Supported features are what /ServiceProviderConfig answers.

SCIM

The base URL is https://<your IdRa address>/api/auth/scim/v2. Send Authorization: Bearer <token>, with a connection's token from Directory → Directory Integrations. Discovery endpoints need no token. See SCIM provisioning.

OperationWhat it doesAuthenticationBody fields
POST /api/auth/scim/v2/GroupsCreate SCIM GroupBearer tokenschemas (required), externalId, displayName (required), members
DELETE /api/auth/scim/v2/Groups/{groupId}Delete SCIM GroupBearer token
GET /api/auth/scim/v2/Groups/{groupId}Get SCIM GroupBearer token
GET /api/auth/scim/v2/GroupsList SCIM GroupsBearer token
PATCH /api/auth/scim/v2/Groups/{groupId}Patch SCIM GroupBearer tokenschemas (required), Operations (required)
PUT /api/auth/scim/v2/Groups/{groupId}Replace SCIM GroupBearer tokenschemas (required), externalId, displayName (required), members
POST /api/auth/scim/v2/UsersCreate SCIM UserBearer tokenschemas (required), userName (required), externalId, displayName, name, emails, title, userType, preferredLanguage, locale, timezone, phoneNumbers, addresses, roles, entitlements, active, urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
DELETE /api/auth/scim/v2/Users/{userId}Delete SCIM UserBearer token
GET /api/auth/scim/v2/Users/{userId}Get SCIM UserBearer token
GET /api/auth/scim/v2/UsersList SCIM UsersBearer token
PATCH /api/auth/scim/v2/Users/{userId}Patch SCIM UserBearer tokenschemas (required), Operations (required)
PUT /api/auth/scim/v2/Users/{userId}Replace SCIM UserBearer tokenschemas (required), userName (required), externalId, displayName, name, emails, title, userType, preferredLanguage, locale, timezone, phoneNumbers, addresses, roles, entitlements, active, urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
GET /api/auth/scim/v2/ServiceProviderConfigGet SCIM service provider configurationNone
GET /api/auth/scim/v2/SchemasList SCIM schemasNone
GET /api/auth/scim/v2/Schemas/{schemaId}Get a SCIM schemaNone
GET /api/auth/scim/v2/ResourceTypesList SCIM resource typesNone
GET /api/auth/scim/v2/ResourceTypes/{resourceTypeId}Get a SCIM resource typeNone

/api/admin

Send one of these:

  • Authorization: SSWS <token>, with a token from Security → API → Tokens. It acts with its creator's current role, spends the tenant's rate limit and obeys its network zones.
  • An admin's console session, which must be MFA-verified. Operations marked fresh MFA also need a second factor within the last 15 minutes, or answer 403 with "fresh": true. So does resetting another admin's password or authenticators. Tokens are exempt, because they have no second factor to step up with.

A service app's OAuth access token works only on /api/v1, not here. The caller's role must hold every permission listed. Errors are { "error": "…" }: 401 unauthorized, 403 forbidden, 403 mfa_required, or a sentence for a 400.

People

OperationWhat it doesPermissionBody fields
GET /api/admin/directory/peopleList peopleuser:list
POST /api/admin/directory/peopleCreate a personuser:createfirstName (required), lastName (required), email (required), profile, groupIds, activate
GET /api/admin/directory/people/{id}Get a personuser:get
GET /api/admin/directory/people/{id}/sessionsList a person's sessionssession:list
PATCH /api/admin/directory/people/{id}Update a person's name and profileperson:editname, profile (required)
POST /api/admin/directory/people/{id}/lifecycle/activateActivate a personperson:edit
POST /api/admin/directory/people/{id}/lifecycle/reactivateReactivate a deprovisioned personperson:edit, user:ban
POST /api/admin/directory/people/{id}/lifecycle/deactivateDeactivate a personuser:ban, user:delete
POST /api/admin/directory/people/{id}/lifecycle/suspendSuspend a personuser:ban
POST /api/admin/directory/people/{id}/lifecycle/unsuspendUnsuspend a personuser:ban
POST /api/admin/directory/people/{id}/lifecycle/reset-passwordSend a person a password resetuser:set-password
POST /api/admin/directory/people/{id}/lifecycle/reset-authenticatorsReset a person's authenticatorsuser:set-password
POST /api/admin/directory/people/{id}/lifecycle/clear-sessionsEnd a person's sessionssession:revoke
POST /api/admin/directory/people/{id}/lifecycle/deleteDelete a deprovisioned personuser:delete
POST /api/admin/directory/people/{id}/lifecycle/unlockClear a person's password lockoutuser:ban
OperationWhat it doesPermissionBody fields
GET /api/admin/directory/user-searchSearch people by name or emailuser:list

Groups

OperationWhat it doesPermissionBody fields
GET /api/admin/directory/groupsList groupsgroup:read
POST /api/admin/directory/groupsCreate a groupgroup:writename (required), description
GET /api/admin/directory/groups/{id}Get a groupgroup:read
PATCH /api/admin/directory/groups/{id}Update a groupgroup:writename, description
DELETE /api/admin/directory/groups/{id}Delete a groupgroup:write
POST /api/admin/directory/groups/{id}/membersAdd membersgroup:membersuserIds (required)
DELETE /api/admin/directory/groups/{id}/members/{userId}Remove a membergroup:members
GET /api/admin/directory/groups/{id}/rulesList a group's membership rulesgroup:read
POST /api/admin/directory/groups/{id}/rulesCreate a membership rulegroup:writename (required), attribute (required), op (required), value (required)
PATCH /api/admin/directory/groups/{id}/rules/{ruleId}Update a membership rulegroup:writename, attribute, op, value, active
DELETE /api/admin/directory/groups/{id}/rules/{ruleId}Delete a membership rulegroup:write
POST /api/admin/directory/groups/{id}/rules/applyQueue a run of a group's membership rulesgroup:write

Profile attributes

OperationWhat it doesPermissionBody fields
GET /api/admin/directory/profile-attributesList profile attributesuser:list
POST /api/admin/directory/profile-attributesCreate a profile attributeuser:updatelabel (required), enumValues, required, uniqueValues, userPermission, key (required), type (required)
PATCH /api/admin/directory/profile-attributes/{key}Update a profile attributeuser:updatelabel, enumValues, required, uniqueValues, userPermission
DELETE /api/admin/directory/profile-attributes/{key}Delete a profile attributeuser:update

Admin roles

OperationWhat it doesPermissionBody fields
GET /api/admin/directory/adminsList admins and their rolesuser:list
PUT /api/admin/directory/admins/{userId}/roles/{role}/targetsSet the targets of an admin's roleuser:set-role (fresh MFA)targets (required)
POST /api/admin/directory/adminsAssign an admin roleuser:set-role (fresh MFA)userId (required), role (required), targets
DELETE /api/admin/directory/admins/{userId}/roles/{role}Remove an admin roleuser:set-role (fresh MFA)

Apps

OperationWhat it doesPermissionBody fields
GET /api/admin/apps/catalogList the app catalogapp:read
GET /api/admin/appsList appsapp:read
POST /api/admin/appsCreate an appapp:writetemplateKey, type, name (required), description, logoUrl, url, visible, oidc, assignMe
GET /api/admin/apps/{id}Get an appapp:read
PATCH /api/admin/apps/{id}Update an appapp:writename, description, logoUrl, url, visible, status
DELETE /api/admin/apps/{id}Delete an appapp:write
GET /api/admin/apps/{id}/oidcGet an app's OIDC settingsapp:read
PATCH /api/admin/apps/{id}/oidcUpdate an app's OIDC settingsapp:writeredirectUris, postLogoutRedirectUris, grantTypes, consentRequired, requirePkce, tokenEndpointAuthMethod, jwks, jwksUri, requireDpop, backchannelLogoutUri, clientCredentialsScopes
POST /api/admin/apps/{id}/oidc/rotate-secretRotate an app's client secretapp:write (fresh MFA)
GET /api/admin/apps/{id}/assignmentsList an app's assignmentsapp:read
GET /api/admin/apps/{id}/users.csvDownload an app's assigned people as CSVapp:read
POST /api/admin/apps/{id}/assignmentsAssign people and groups to an appapp:writeuserIds, groupIds
DELETE /api/admin/apps/{id}/assignments/{assignmentId}Remove an assignmentapp:write

SAML apps and signing keys

OperationWhat it doesPermissionBody fields
GET /api/admin/saml/apps/{appId}Get an app's SAML settingsapp:read
PUT /api/admin/saml/apps/{appId}Set an app's SAML settingsapp:writeentityId (required), acsUrl (required), acsUrls, audience, defaultRelayState, nameIdFormat (required), nameIdAttribute (required), nameIdExpression, attributes (required), signResponse (required), signatureAlgorithm, spCertificate, requireSignedRequests, honorForceAuthn, honorAuthnContext
POST /api/admin/saml/apps/{appId}/previewPreview the assertion for a personapp:read, user:getconfig (required), email
POST /api/admin/saml/apps/{appId}/importRead SAML settings from service provider metadata XMLapp:writexml (required)
GET /api/admin/saml/keysList signing keyssettings:read
POST /api/admin/saml/keys/saml/rotateRotate the SAML signing keysettings:write (fresh MFA)
POST /api/admin/saml/keys/saml/{id}/retireRetire a SAML signing keysettings:write (fresh MFA)
POST /api/admin/saml/keys/oidc/rotateRotate the OIDC signing keysettings:write (fresh MFA)

API tokens and service app grants

OperationWhat it doesPermissionBody fields
GET /api/admin/api-access/tokens/service-appsList service apps and their grantsapp:read
PUT /api/admin/api-access/tokens/service-apps/{id}Set a service app's scope grantsapp:write, policy:write (fresh MFA)scopes (required)
GET /api/admin/api-access/tokensList API tokenssettings:read
POST /api/admin/api-access/tokensCreate an API tokensettings:write (fresh MFA)name (required), expiresInDays, allowedZoneIds
DELETE /api/admin/api-access/tokens/{id}Delete an API tokensettings:write (fresh MFA)

Dynamic client registration

OperationWhat it doesPermissionBody fields
GET /api/admin/api-access/client-registrationGet dynamic client registration settingssettings:read
PUT /api/admin/api-access/client-registrationTurn dynamic client registration on or offsettings:write, app:write (fresh MFA)enabled (required)
POST /api/admin/api-access/client-registration/tokensCreate a registration tokensettings:write, app:write (fresh MFA)name (required), expiresInDays (required)
DELETE /api/admin/api-access/client-registration/tokens/{id}Delete a registration tokensettings:write, app:write (fresh MFA)

Authorization servers

OperationWhat it doesPermissionBody fields
GET /api/admin/api-access/serversList authorization serversapi_access:read
POST /api/admin/api-access/serversCreate an authorization serverapi_access:writename (required), allowedScopes, accessTokenTtl, customClaims, disabled, identifier (required)
GET /api/admin/api-access/servers/{id}Get an authorization serverapi_access:read
PATCH /api/admin/api-access/servers/{id}Update an authorization serverapi_access:writename, allowedScopes, accessTokenTtl, customClaims, disabled
DELETE /api/admin/api-access/servers/{id}Delete an authorization serverapi_access:write
POST /api/admin/api-access/servers/{id}/clientsAllow a client on an authorization serverapi_access:writeclientId (required)
DELETE /api/admin/api-access/servers/{id}/clients/{clientId}Remove a client from a serverapi_access:write
POST /api/admin/api-access/servers/{id}/rulesCreate an access ruleapi_access:writename (required), priority (required), enabled (required), conditions (required), action (required)
PATCH /api/admin/api-access/rules/{ruleId}Update an access ruleapi_access:writename, priority, enabled, conditions, action
DELETE /api/admin/api-access/rules/{ruleId}Delete an access ruleapi_access:write
POST /api/admin/api-access/servers/{id}/previewPreview which rule a token request matchesapi_access:readclientId (required), grantType (required), scopes (required), userId

Outbound provisioning

OperationWhat it doesPermissionBody fields
GET /api/admin/integrations/provisioning/apps/{appId}Get an app's provisioning settingsapp:read
PUT /api/admin/integrations/provisioning/apps/{appId}Set an app's provisioning settingsapp:writeenabled (required), baseUrl (required), token, createUsers (required), updateUsers (required), deactivateUsers (required), pushGroups (required), mappings (required)
POST /api/admin/integrations/provisioning/apps/{appId}/testTest a SCIM base URL and tokenapp:writebaseUrl, token
POST /api/admin/integrations/provisioning/apps/{appId}/pushPush everyone assigned to the appapp:write
POST /api/admin/integrations/provisioning/apps/{appId}/users/{userId}/pushPush one personapp:write
POST /api/admin/integrations/provisioning/apps/{appId}/groupsAdd a pushed groupapp:writegroupId (required)
POST /api/admin/integrations/provisioning/apps/{appId}/groups/{groupId}/pushPush one groupapp:write
DELETE /api/admin/integrations/provisioning/apps/{appId}/groups/{groupId}Stop pushing a groupapp:write

Inbound SCIM connections

OperationWhat it doesPermissionBody fields
GET /api/admin/integrations/scimList inbound SCIM connectionsuser:list
POST /api/admin/integrations/scimCreate a connection and its bearer tokenuser:create, user:update, user:ban (fresh MFA)name (required)
POST /api/admin/integrations/scim/{connectionId}/rotateRotate a connection's bearer tokenuser:create, user:update, user:ban (fresh MFA)
POST /api/admin/integrations/scim/{connectionId}/revokeRevoke a connection's bearer tokenuser:create, user:update, user:ban (fresh MFA)

Identity providers

OperationWhat it doesPermissionBody fields
GET /api/admin/integrations/identity-providers/routing-rulesList routing rulespolicy:read
POST /api/admin/integrations/identity-providers/routing-rulesCreate a routing rulepolicy:write (fresh MFA)name (required), priority, enabled, conditions (required), providerId (required)
PATCH /api/admin/integrations/identity-providers/routing-rules/{id}Update a routing rulepolicy:write (fresh MFA)name, priority, enabled, conditions, providerId
DELETE /api/admin/integrations/identity-providers/routing-rules/{id}Delete a routing rulepolicy:write (fresh MFA)
GET /api/admin/integrations/identity-providers/domain-proofsList domain proofspolicy:read
POST /api/admin/integrations/identity-providers/domain-proofsStart proving a domainpolicy:write (fresh MFA)domain (required)
POST /api/admin/integrations/identity-providers/domain-proofs/{domain}/verifyCheck a domain proofpolicy:write (fresh MFA)
DELETE /api/admin/integrations/identity-providers/domain-proofs/{domain}Delete a domain proofpolicy:write (fresh MFA)
GET /api/admin/integrations/identity-providersList identity providerspolicy:read
POST /api/admin/integrations/identity-providersAdd an identity providerpolicy:write (fresh MFA)See the JSON file
GET /api/admin/integrations/identity-providers/{providerId}Get an identity providerpolicy:read
PATCH /api/admin/integrations/identity-providers/{providerId}Update an identity providerpolicy:write (fresh MFA)name, domains, jit, idpInitiated, slo, attributeMap, groupClaim, groupMap
PUT /api/admin/integrations/identity-providers/{providerId}/linkingSet account linkingpolicy:write (fresh MFA)linkExisting (required), linkDomains (required), trustEmail
DELETE /api/admin/integrations/identity-providers/{providerId}Delete an identity providerpolicy:write (fresh MFA)

Webhooks

OperationWhat it doesPermissionBody fields
GET /api/admin/integrations/webhooksList webhookssettings:read
POST /api/admin/integrations/webhooksCreate a webhooksettings:writename (required), url (required), eventTypes (required), filter, format, headers
GET /api/admin/integrations/webhooks/{id}Get a webhooksettings:read
PATCH /api/admin/integrations/webhooks/{id}Update a webhooksettings:writename, url, eventTypes, filter, format, headers, enabled
DELETE /api/admin/integrations/webhooks/{id}Delete a webhooksettings:write
POST /api/admin/integrations/webhooks/{id}/testSend a webhook a test deliverysettings:write

Log streams

OperationWhat it doesPermissionBody fields
GET /api/admin/logs/streamsList log streamssettings:read
POST /api/admin/logs/streamsCreate a log streamsettings:writename (required), type (required), url (required), token (required), header
PATCH /api/admin/logs/streams/{id}Update a log streamsettings:writename, url, token, header, enabled
DELETE /api/admin/logs/streams/{id}Delete a log streamsettings:write
POST /api/admin/logs/streams/{id}/testSend a log stream a test eventsettings:write

Inline hooks

OperationWhat it doesPermissionBody fields
GET /api/admin/logs/inline-hooksList inline hookssettings:read
POST /api/admin/logs/inline-hooksCreate an inline hooksettings:writename (required), type (required), url (required), keyId (required), onFailure, auth
PATCH /api/admin/logs/inline-hooks/{id}Update an inline hooksettings:writename, url, keyId, onFailure, auth, enabled
DELETE /api/admin/logs/inline-hooks/{id}Delete an inline hooksettings:write
POST /api/admin/logs/inline-hooks/{id}/testCall an inline hook with a test requestsettings:write

Hook keys and log integrity

OperationWhat it doesPermissionBody fields
GET /api/admin/logs/hook-keysList hook keyssettings:read
POST /api/admin/logs/hook-keysCreate a hook keysettings:write (fresh MFA)name (required)
DELETE /api/admin/logs/hook-keys/{id}Delete a hook keysettings:write (fresh MFA)
POST /api/admin/logs/integrity/verifyVerify the System Log's integrityreport:read

What's left out

Mounted routes that aren't described, by path prefix.

PrefixRoutesWhy
/api/admin/directory/custom-roles4Custom admin roles: still changing
/api/admin/directory/resource-sets4Resource sets: still changing
/api/admin/directory/custom-grants2Custom role grants: still changing
/api/admin/directory/admins/me1The console asks about its own session
/api/admin/directory/impersonation2The console's impersonated session
/api/admin/directory/people/import5CSV import wizard
/api/admin/directory/people/:id/impersonate1Sign in as a person, from the console
/api/admin/directory/okta-import4Migration wizard, see Okta import
/api/admin/security40Console screens, not written up as an integration surface yet
/api/admin/itp33Console screens, not written up as an integration surface yet
/api/admin/posture38Console screens, not written up as an integration surface yet
/api/admin/pam18Console screens, not written up as an integration surface yet
/api/admin/partners20Console screens, not written up as an integration surface yet
/api/admin/reports11Console screens, not written up as an integration surface yet
/api/admin/settings13Console screens, not written up as an integration surface yet
/api/admin/devices17Console screens, not written up as an integration surface yet
/api/admin/privacy3Console screens, not written up as an integration surface yet
/api/admin/org-export3Needs a console session with MFA, so API tokens are refused
/api/admin/gateway2Console screens, not written up as an integration surface yet
/api/admin/factors19Console screens, not written up as an integration surface yet
/api/admin/domains7Console screens, not written up as an integration surface yet
/api/me17The signed-in person's own account
/api/factors17The signed-in person's own factors
/api/partner17Partner portal
/api/public4Sign-in page data
/api/pam1The PAM command line tool
/api/platform25Operating a multi-tenant deployment
/api/device-remediation1Device remediation page
/api/hooks/fleet1Inbound webhook from Fleet
/api/auth/.well-known1OIDC discovery, a standard document
/.well-known3OAuth and SSF discovery, standard documents
/sso/saml5SAML protocol endpoints
/gateway2Access gateway protocol endpoints
/ssf12Shared Signals protocol endpoints
/healthz1Uptime check
/readyz1Uptime check
/metrics1Operator metrics
/robots.txt1Crawlers
/*1The web app

API reference

Every operation of IdRa's /api/v1 management API, which is compatible with core Okta resources, with its OAuth scope and body fields. Also available as an OpenAPI file.

idra CLI

SSH into servers with short-lived certificates issued by IdRa (Privileged Access).

On this page

What this reference doesn't coverSCIM/api/adminPeoplePeople searchGroupsProfile attributesAdmin rolesAppsSAML apps and signing keysAPI tokens and service app grantsDynamic client registrationAuthorization serversOutbound provisioningInbound SCIM connectionsIdentity providersWebhooksLog streamsInline hooksHook keys and log integrityWhat's left out