# API reference (https://docs.idra.zone/docs/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.

Paths are under `/api/v1`. This page and [openapi.json](https://docs.idra.zone/openapi.json) are generated from IdRa's router, and a test fails if they list a path the router doesn't have. Start with [Admin API](https://docs.idra.zone/docs/admin-api) for tokens, paging, errors and how IdRa differs from Okta.

131 operations are listed. On 2026-10-31, they answered 131 of the 815 operations in Okta's Node SDK (`@okta/okta-sdk-nodejs` 8.2.0), so most of Okta's API isn't here. A matching path shows that IdRa has the operation, not that it behaves the same as Okta.

## What this reference doesn't cover

- Responses aren't described. They follow the shape of the matching Okta resource: check the [differences](https://docs.idra.zone/docs/admin-api#differences-from-okta).
- Request bodies aren't described for `POST /policies`, `PUT /policies/{id}`, `POST /policies/{id}/rules`, `PUT /policies/{id}/rules/{ruleId}`, because they're validated inside the handler.
- Query parameters are listed in the summary, or come from the route's schema where it has one. Paging and filters are in the [conventions](https://docs.idra.zone/docs/admin-api#conventions).
- Only `/api/v1`. The console's `/api/admin`, the OIDC and SAML endpoints under `/api/auth` and `/sso/saml`, the Okta path aliases under the issuer, and SCIM aren't here.

## Users

| Operation | What it does | OAuth scope | Body fields |
| --- | --- | --- | --- |
| `GET /users` | List people. Query: `q`, `filter`, `search`, `limit`, `after` | `okta.users.read` |  |
| `POST /users` | Create a person. Query: `activate` | `okta.users.manage` | `profile` (required), `credentials`, `groupIds` |
| `GET /users/{id}` | Get a person by ID or login | `okta.users.read` |  |
| `POST /users/{id}` | Update a person, changing only the fields sent | `okta.users.manage` | `profile`, `credentials` |
| `PUT /users/{id}` | Replace a person's profile | `okta.users.manage` | `profile`, `credentials` |
| `DELETE /users/{id}` | Deactivate a person. A second call deletes them | `okta.users.manage` |  |
| `POST /users/{id}/lifecycle/activate` | Activate a person | `okta.users.manage` |  |
| `POST /users/{id}/lifecycle/reactivate` | Reactivate a person | `okta.users.manage` |  |
| `POST /users/{id}/lifecycle/deactivate` | Deactivate a person | `okta.users.manage` |  |
| `POST /users/{id}/lifecycle/suspend` | Suspend a person | `okta.users.manage` |  |
| `POST /users/{id}/lifecycle/unsuspend` | Unsuspend a person | `okta.users.manage` |  |
| `POST /users/{id}/lifecycle/unlock` | Unlock a person | `okta.users.manage` |  |
| `POST /users/{id}/lifecycle/reset_password` | Send a password reset to a person | `okta.users.manage` |  |
| `POST /users/{id}/lifecycle/reset_factors` | Reset the factors of a person | `okta.users.manage` |  |
| `POST /users/{id}/credentials/change_password` | Change a password, given the old one | `okta.users.manage` | `oldPassword` (required), `newPassword` (required) |
| `GET /users/{id}/groups` | List a person's groups | `okta.users.read` |  |
| `GET /users/{id}/appLinks` | List a person's app links | `okta.users.read` |  |
| `GET /users/{id}/factors` | List a person's factors | `okta.users.read` |  |
| `DELETE /users/{id}/factors/{factorId}` | Remove a factor | `okta.users.manage` |  |
| `DELETE /users/{id}/sessions` | End a person's sessions | `okta.users.manage` |  |
| `GET /users/{id}/roles` | List a person's admin roles | `okta.roles.read` |  |
| `POST /users/{id}/roles` | Assign an admin role | `okta.roles.manage` | `type` (required) |
| `DELETE /users/{id}/roles/{roleId}` | Remove an admin role | `okta.roles.manage` |  |
| `GET /users/{id}/risk` | Get a person's risk level | `okta.userRisk.read` |  |
| `PUT /users/{id}/risk` | Set a person's risk level | `okta.userRisk.manage` | `riskLevel` (required) |

## Groups

| Operation | What it does | OAuth scope | Body fields |
| --- | --- | --- | --- |
| `GET /groups/rules` | List group rules | `okta.groups.read` |  |
| `POST /groups/rules` | Create a group rule | `okta.groups.manage` | `name` (required), `conditions` (required), `actions` (required) |
| `GET /groups/rules/{ruleId}` | Get a group rule | `okta.groups.read` |  |
| `PUT /groups/rules/{ruleId}` | Update a group rule | `okta.groups.manage` | `name` (required), `conditions` (required), `actions` (required) |
| `DELETE /groups/rules/{ruleId}` | Delete a group rule | `okta.groups.manage` |  |
| `POST /groups/rules/{ruleId}/lifecycle/activate` | Activate a group rule | `okta.groups.manage` |  |
| `POST /groups/rules/{ruleId}/lifecycle/deactivate` | Deactivate a group rule | `okta.groups.manage` |  |
| `GET /groups` | List groups. Query: `q`, `filter`, `search`, `limit`, `after` | `okta.groups.read` |  |
| `POST /groups` | Create a group | `okta.groups.manage` | `profile` (required) |
| `GET /groups/{id}` | Get a group | `okta.groups.read` |  |
| `PUT /groups/{id}` | Update a group | `okta.groups.manage` | `profile` (required) |
| `DELETE /groups/{id}` | Delete a group | `okta.groups.manage` |  |
| `GET /groups/{id}/users` | List a group's members | `okta.groups.read` |  |
| `PUT /groups/{id}/users/{userId}` | Add a member | `okta.groups.manage` |  |
| `DELETE /groups/{id}/users/{userId}` | Remove a member | `okta.groups.manage` |  |
| `GET /groups/{id}/apps` | List apps assigned to a group | `okta.groups.read` |  |

## System Log

| Operation | What it does | OAuth scope | Body fields |
| --- | --- | --- | --- |
| `GET /logs` | Read the System Log. Query: `since`, `until`, `filter`, `q`, `sortOrder`, `limit` | `okta.logs.read` |  |

## Apps

| Operation | What it does | OAuth scope | Body fields |
| --- | --- | --- | --- |
| `GET /apps/{id}/grants` | List a service app's `okta.*` scope grants | `okta.appGrants.read` |  |
| `POST /apps/{id}/grants` | Grant a service app an `okta.*` scope | `okta.appGrants.manage` | `issuer`, `scopeId` (required) |
| `DELETE /apps/{id}/grants/{scopeId}` | Remove a scope grant | `okta.appGrants.manage` |  |
| `GET /apps` | List apps | `okta.apps.read` |  |
| `POST /apps` | Create a bookmark, OIDC (web, browser, native, service) or SAML app | `okta.apps.manage` | See `openapi.json` |
| `GET /apps/{id}` | Get an app | `okta.apps.read` |  |
| `PUT /apps/{id}` | Update an app | `okta.apps.manage` | See `openapi.json` |
| `DELETE /apps/{id}` | Delete an inactive app | `okta.apps.manage` |  |
| `GET /apps/{id}/credentials/keys` | List a SAML app's signing certificates, shared across the tenant | `okta.apps.read` |  |
| `POST /apps/{id}/lifecycle/activate` | Activate an app | `okta.apps.manage` |  |
| `POST /apps/{id}/lifecycle/deactivate` | Deactivate an app | `okta.apps.manage` |  |
| `GET /apps/{id}/users` | List people assigned to an app | `okta.apps.read` |  |
| `POST /apps/{id}/users` | Assign a person to an app | `okta.apps.manage` | `scope`, `credentials`, `profile` |
| `GET /apps/{id}/users/{userId}` | Get a person's assignment | `okta.apps.read` |  |
| `DELETE /apps/{id}/users/{userId}` | Remove a person's assignment | `okta.apps.manage` |  |
| `GET /apps/{id}/groups` | List groups assigned to an app | `okta.apps.read` |  |
| `PUT /apps/{id}/groups/{groupId}` | Assign a group to an app | `okta.apps.manage` |  |
| `GET /apps/{id}/groups/{groupId}` | Get a group's assignment | `okta.apps.read` |  |
| `DELETE /apps/{id}/groups/{groupId}` | Remove a group's assignment | `okta.apps.manage` |  |
| `PUT /apps/{id}/policies/{policyId}` | Set an app's sign-on policy | `okta.apps.manage` |  |

## Authorization servers

| Operation | What it does | OAuth scope | Body fields |
| --- | --- | --- | --- |
| `GET /authorizationServers` | List authorization servers | `okta.authorizationServers.read` |  |
| `POST /authorizationServers` | Create an authorization server | `okta.authorizationServers.manage` | `name` (required), `description`, `audiences` (required), `issuerMode`, `issuer`, `credentials` |
| `GET /authorizationServers/{id}` | Get an authorization server | `okta.authorizationServers.read` |  |
| `PUT /authorizationServers/{id}` | Update an authorization server | `okta.authorizationServers.manage` | `name` (required), `description`, `audiences` (required), `issuerMode`, `issuer`, `credentials` |
| `DELETE /authorizationServers/{id}` | Delete an authorization server | `okta.authorizationServers.manage` |  |
| `POST /authorizationServers/{id}/lifecycle/activate` | Activate an authorization server | `okta.authorizationServers.manage` |  |
| `POST /authorizationServers/{id}/lifecycle/deactivate` | Deactivate an authorization server | `okta.authorizationServers.manage` |  |
| `GET /authorizationServers/{id}/scopes` | List scopes | `okta.authorizationServers.read` |  |
| `POST /authorizationServers/{id}/scopes` | Create a scope | `okta.authorizationServers.manage` | `name` (required), `description`, `displayName`, `consent`, `metadataPublish`, `default`, `optional` |
| `GET /authorizationServers/{id}/scopes/{scopeId}` | Get a scope | `okta.authorizationServers.read` |  |
| `PUT /authorizationServers/{id}/scopes/{scopeId}` | Update a scope | `okta.authorizationServers.manage` | `name` (required), `description`, `displayName`, `consent`, `metadataPublish`, `default`, `optional` |
| `DELETE /authorizationServers/{id}/scopes/{scopeId}` | Delete a scope | `okta.authorizationServers.manage` |  |
| `GET /authorizationServers/{id}/claims` | List claims | `okta.authorizationServers.read` |  |
| `POST /authorizationServers/{id}/claims` | Create a claim | `okta.authorizationServers.manage` | `name` (required), `claimType` (required), `valueType` (required), `value` (required), `alwaysIncludeInToken`, `conditions` |
| `GET /authorizationServers/{id}/claims/{claimId}` | Get a claim | `okta.authorizationServers.read` |  |
| `PUT /authorizationServers/{id}/claims/{claimId}` | Update a claim | `okta.authorizationServers.manage` | `name` (required), `claimType` (required), `valueType` (required), `value` (required), `alwaysIncludeInToken`, `conditions` |
| `DELETE /authorizationServers/{id}/claims/{claimId}` | Delete a claim | `okta.authorizationServers.manage` |  |
| `GET /authorizationServers/{id}/policies` | List access policies | `okta.authorizationServers.read` |  |
| `POST /authorizationServers/{id}/policies` | Create an access policy | `okta.authorizationServers.manage` | `type` (required), `name` (required), `description`, `priority`, `conditions` (required) |
| `GET /authorizationServers/{id}/policies/{policyId}` | Get an access policy | `okta.authorizationServers.read` |  |
| `PUT /authorizationServers/{id}/policies/{policyId}` | Update an access policy | `okta.authorizationServers.manage` | `type` (required), `name` (required), `description`, `priority`, `conditions` (required) |
| `DELETE /authorizationServers/{id}/policies/{policyId}` | Delete an access policy | `okta.authorizationServers.manage` |  |
| `POST /authorizationServers/{id}/policies/{policyId}/lifecycle/activate` | Activate an access policy | `okta.authorizationServers.manage` |  |
| `POST /authorizationServers/{id}/policies/{policyId}/lifecycle/deactivate` | Deactivate an access policy | `okta.authorizationServers.manage` |  |
| `GET /authorizationServers/{id}/policies/{policyId}/rules` | List access rules | `okta.authorizationServers.read` |  |
| `POST /authorizationServers/{id}/policies/{policyId}/rules` | Create an access rule | `okta.authorizationServers.manage` | `type` (required), `name` (required), `priority`, `conditions` (required), `actions` |
| `GET /authorizationServers/{id}/policies/{policyId}/rules/{ruleId}` | Get an access rule | `okta.authorizationServers.read` |  |
| `PUT /authorizationServers/{id}/policies/{policyId}/rules/{ruleId}` | Update an access rule | `okta.authorizationServers.manage` | `type` (required), `name` (required), `priority`, `conditions` (required), `actions` |
| `DELETE /authorizationServers/{id}/policies/{policyId}/rules/{ruleId}` | Delete an access rule | `okta.authorizationServers.manage` |  |
| `POST /authorizationServers/{id}/policies/{policyId}/rules/{ruleId}/lifecycle/activate` | Activate an access rule | `okta.authorizationServers.manage` |  |
| `POST /authorizationServers/{id}/policies/{policyId}/rules/{ruleId}/lifecycle/deactivate` | Deactivate an access rule | `okta.authorizationServers.manage` |  |

## Policies

| Operation | What it does | OAuth scope | Body fields |
| --- | --- | --- | --- |
| `POST /policies/simulate` | Simulate which rules a person matches at an app | `okta.policies.manage` | `appInstance` (required), `policyTypes`, `policyContext` (required) |
| `GET /policies` | List policies of a `type`: `OKTA_SIGN_ON`, `ACCESS_POLICY` or `PASSWORD` | `okta.policies.read` |  |
| `POST /policies` | Create a `PASSWORD` policy | `okta.policies.manage` |  |
| `GET /policies/{id}` | Get a policy | `okta.policies.read` |  |
| `PUT /policies/{id}` | Update a policy | `okta.policies.manage` |  |
| `DELETE /policies/{id}` | Delete a policy | `okta.policies.manage` |  |
| `POST /policies/{id}/lifecycle/activate` | Activate a policy | `okta.policies.manage` |  |
| `POST /policies/{id}/lifecycle/deactivate` | Deactivate a policy | `okta.policies.manage` |  |
| `GET /policies/{id}/rules` | List a policy's rules | `okta.policies.read` |  |
| `POST /policies/{id}/rules` | Create a rule | `okta.policies.manage` |  |
| `GET /policies/{id}/rules/{ruleId}` | Get a rule | `okta.policies.read` |  |
| `PUT /policies/{id}/rules/{ruleId}` | Update a rule | `okta.policies.manage` |  |
| `DELETE /policies/{id}/rules/{ruleId}` | Delete a rule | `okta.policies.manage` |  |
| `POST /policies/{id}/rules/{ruleId}/lifecycle/activate` | Activate a rule | `okta.policies.manage` |  |
| `POST /policies/{id}/rules/{ruleId}/lifecycle/deactivate` | Deactivate a rule | `okta.policies.manage` |  |

## Network zones

| Operation | What it does | OAuth scope | Body fields |
| --- | --- | --- | --- |
| `GET /zones` | List network zones | `okta.networkZones.read` |  |
| `POST /zones` | Create an `IP` or `DYNAMIC` zone | `okta.networkZones.manage` | See `openapi.json` |
| `GET /zones/{id}` | Get a zone | `okta.networkZones.read` |  |
| `PUT /zones/{id}` | Update a zone | `okta.networkZones.manage` | See `openapi.json` |
| `DELETE /zones/{id}` | Delete a zone | `okta.networkZones.manage` |  |
| `POST /zones/{id}/lifecycle/activate` | Answers 200. Zones are always active | `okta.networkZones.manage` |  |
| `POST /zones/{id}/lifecycle/deactivate` | Answers 200 and changes nothing. Zones are always active | `okta.networkZones.manage` |  |

## Event hooks

| Operation | What it does | OAuth scope | Body fields |
| --- | --- | --- | --- |
| `GET /eventHooks` | List event hooks | `okta.eventHooks.read` |  |
| `POST /eventHooks` | Create an event hook | `okta.eventHooks.manage` | `name` (required), `description`, `events` (required), `channel` (required) |
| `GET /eventHooks/{id}` | Get an event hook | `okta.eventHooks.read` |  |
| `PUT /eventHooks/{id}` | Update an event hook | `okta.eventHooks.manage` | `name` (required), `description`, `events` (required), `channel` (required) |
| `DELETE /eventHooks/{id}` | Delete an inactive event hook | `okta.eventHooks.manage` |  |
| `POST /eventHooks/{id}/lifecycle/activate` | Activate an event hook | `okta.eventHooks.manage` |  |
| `POST /eventHooks/{id}/lifecycle/deactivate` | Deactivate an event hook | `okta.eventHooks.manage` |  |
| `POST /eventHooks/{id}/lifecycle/verify` | Verify the endpoint of an event hook | `okta.eventHooks.manage` |  |

## Devices

| Operation | What it does | OAuth scope | Body fields |
| --- | --- | --- | --- |
| `GET /devices` | List devices. Query: `search`, `limit`, `after` | `okta.devices.read` |  |
| `GET /devices/{id}` | Get a device | `okta.devices.read` |  |
| `DELETE /devices/{id}` | Delete a deactivated device | `okta.devices.manage` |  |
| `GET /devices/{id}/users` | List a device's user | `okta.devices.read` |  |
| `POST /devices/{id}/lifecycle/activate` | Activate a device | `okta.devices.manage` |  |
| `POST /devices/{id}/lifecycle/deactivate` | Deactivate a device | `okta.devices.manage` |  |
| `POST /devices/{id}/lifecycle/suspend` | Suspend a device | `okta.devices.manage` |  |
| `POST /devices/{id}/lifecycle/unsuspend` | Unsuspend a device | `okta.devices.manage` |  |