Home

Okta (version v1.*.*)

activate_application#

Activates an inactive application.

Parameters

appId (required)#

Type: string

activate_factor#

The sms,call and token:software:totp factor types require activation to complete the enrollment process.

Parameters

factorId (required)#

Factor ID

Type: string

$body#

Type: object

{
  "stateToken" : "state token for current transaction",
  "passCode" : "OTP generated by device"
}

activate_factor_by_user#

The sms and token:software:totp factor types require activation to complete the enrollment process.

Parameters

factorId (required)#

Type: string

userId (required)#

Type: string

$body#

Type: object

{
  "answer" : "string",
  "nextPassCode" : "string",
  "tokenLifetimeSeconds" : "integer",
  "passCode" : "string",
  "activationToken" : "string"
}

activate_policy#

Parameters

policyId (required)#

Type: string

activate_policy_rule#

Parameters

policyId (required)#

Type: string

ruleId (required)#

Type: string

activate_rule#

Activates a specific group rule by id from your organization

Parameters

ruleId (required)#

Type: string

activate_user#

Activates a user. This operation can only be performed on users with a STAGED status. Activation of a user is an asynchronous operation. The user will have the transitioningToStatus property with a value of ACTIVE during activation to indicate that the user hasn't completed the asynchronous operation. The user will have a status of ACTIVE when the activation process is complete.

Parameters

sendEmail (required)#

Sends an activation email to the user if true

Type: boolean

userId (required)#

Type: string

add_factor#

Enrolls a user with a supported factor

Parameters

userId (required)#

Type: string

$body#

Factor

Type: object

{
  "deviceType" : "string",
  "rechallengeExistingFactor" : "boolean",
  "_links" : "object",
  "profile" : { },
  "sessionId" : "string",
  "userId" : "string",
  "mfaStateTokenId" : "string",
  "_embedded" : "object",
  "provider" : "string. Possible values: OKTA | RSA | GOOGLE | SYMANTEC | DUO | YUBICO | FIDO",
  "factorType" : "string. Possible values: push | sms | call | token | token:software:totp | token:hardware | question | web | email | u2f | webauthn | token:software | custom",
  "verify" : {
    "answer" : "string",
    "nextPassCode" : "string",
    "tokenLifetimeSeconds" : "integer",
    "passCode" : "string",
    "activationToken" : "string"
  },
  "tokenLifetimeSeconds" : "integer",
  "id" : "string",
  "device" : "string",
  "status" : "string. Possible values: PENDING_ACTIVATION | ACTIVE | INACTIVE | NOT_SETUP | ENROLLED | DISABLED | EXPIRED"
}

activate#

Type: boolean

templateId#

id of SMS template (only for SMS factor)

Type: string

tokenLifetimeSeconds#

Type: integer

updatePhone#

Type: boolean

add_group_target_to_role#

Success

Parameters

groupId (required)#

Type: string

roleId (required)#

Type: string

userId (required)#

Type: string

add_policy_rule#

Parameters

policyId (required)#

Type: string

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "system" : "boolean",
  "created" : "date-time",
  "id" : "string",
  "priority" : "integer",
  "type" : "string. Possible values: SIGN_ON | PASSWORD",
  "status" : "string. Possible values: ACTIVE | INACTIVE"
}

activate#

Type: boolean

add_role_to_user#

Assigns a role to a user.

Parameters

userId (required)#

Type: string

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "_embedded" : "object",
  "_links" : "object",
  "created" : "date-time",
  "description" : "string",
  "id" : "string",
  "label" : "string",
  "type" : "string",
  "assignmentType" : "string. Possible values: GROUP | USER",
  "status" : "string. Possible values: ACTIVE | INACTIVE"
}

add_user_to_group#

Adds a user to a group with OKTA_GROUP type.

Parameters

groupId (required)#

Type: string

userId (required)#

Type: string

answer_recovery_question#

Answers the user's recovery question to ensure only the end user redeemed the recovery token for recovery transaction with a RECOVERY status.

Parameters

$body#

Type: object

{
  "answer" : "answer to user's recovery question",
  "stateToken" : "state token for current recovery transaction"
}

assign_user_to_application#

Assigns an user to an application with credentials and an app-specific profile. Profile mappings defined for the application are first applied before applying any profile properties specified in the request.

Parameters

appId (required)#

Type: string

$body#

Type: object

{
  "_links" : "object",
  "credentials" : {
    "password" : {
      "value" : "password"
    },
    "userName" : "string"
  },
  "created" : "date-time",
  "profile" : "object",
  "syncState" : "string",
  "externalId" : "string",
  "lastUpdated" : "date-time",
  "passwordChanged" : "date-time",
  "lastSync" : "date-time",
  "_embedded" : "object",
  "scope" : "string",
  "statusChanged" : "date-time",
  "id" : "string",
  "status" : "string"
}

authentication#

Every authentication transaction starts with primary authentication which validates a user's primary password credential. Password Policy, MFA Policy, and Sign-On Policy are evaluated during primary authentication to determine if the user's password is expired, a factor should be enrolled, or additional verification is required. The transaction state of the response depends on the user's status, group memberships and assigned policies.

Parameters

$body#

Type: object

{
  "relayState" : "Optional state value that is persisted for the lifetime of the authentication transaction",
  "password" : "User's password credential",
  "audience" : "App ID of the target app the user is signing into",
  "oldPassword" : "User's current password that is expired or about to expire",
  "options" : {
    "warnBeforePasswordExpired" : "Transitions transaction to PASSWORD_WARN state before SUCCESS if the user's password is about to expire and within their password policy warn period",
    "multiOptionalFactorEnroll" : "Transitions transaction back to MFA_ENROLL state after successful factor enrollment when additional optional factors are available for enrollment"
  },
  "context" : {
    "deviceToken" : "A globally unique ID identifying the user's client device or user agent"
  },
  "newPassword" : "New password for user",
  "stateToken" : "state token for current transaction",
  "username" : "User's non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)",
  "token" : "Token received as part of activation user request"
}

cancel_transaction#

Cancels the current transaction and revokes the state token.

Parameters

$body#

Type: object

{
  "stateToken" : "state token for a transaction"
}

change_password#

This operation changes a user's password by providing the existing password and the new password for authentication transactions with either the PASSWORD_EXPIRED or PASSWORD_WARN state. A user must change their expired password for an authentication transaction with PASSWORD_EXPIRED status to successfully complete the transaction. A user may opt-out of changing their password (skip) when the transaction has a PASSWORD_WARN status.

Parameters

$body#

Type: object

{
  "oldPassword" : "User's current password that is expired or about to expire",
  "newPassword" : "New password for user",
  "stateToken" : "state token for current transaction"
}

change_password_by_user#

Changes a user's password by validating the user's current password. This operation can only be performed on users in STAGED, ACTIVE, PASSWORD_EXPIRED, or RECOVERY status that have a valid password credential

Parameters

userId (required)#

Type: string

$body#

Type: object

{
  "oldPassword" : {
    "value" : "password"
  },
  "newPassword" : {
    "value" : "password"
  }
}

strict#

Type: boolean

change_recovery_question#

Changes a user's recovery question & answer credential by validating the user's current password. This operation can only be performed on users in STAGED, ACTIVE or RECOVERY status that have a valid password credential

Parameters

userId (required)#

Type: string

$body#

Type: object

{
  "emails" : [ {
    "type" : "string. Possible values: PRIMARY | SECONDARY",
    "value" : "string",
    "status" : "string. Possible values: VERIFIED | UNVERIFIED"
  } ],
  "password" : {
    "value" : "password"
  },
  "provider" : {
    "name" : "string",
    "type" : "string. Possible values: ACTIVE_DIRECTORY | FEDERATION | LDAP | OKTA | SOCIAL | IMPORT"
  },
  "recovery_question" : {
    "answer" : "string",
    "question" : "string"
  }
}

clone_application_key#

Clones a X.509 certificate for an application key credential from a source application to target application.

Parameters

appId (required)#

Type: string

keyId (required)#

Type: string

targetAid (required)#

Unique key of the target Application

Type: string

create_application#

Adds a new application to your Okta organization.

Parameters

$body#

Type: object

{
  "settings" : {
    "app" : { },
    "inlineHookId" : "string",
    "implicitAssignment" : "boolean",
    "notifications" : {
      "vpn" : {
        "helpUrl" : "string",
        "message" : "string",
        "network" : {
          "include" : [ "string" ],
          "connection" : "string",
          "exclude" : [ "string" ]
        }
      }
    }
  },
  "visibility" : {
    "hide" : {
      "web" : "boolean",
      "iOS" : "boolean"
    },
    "appLinks" : "object",
    "autoSubmitToolbar" : "boolean"
  },
  "_links" : "object",
  "accessibility" : {
    "errorRedirectUrl" : "string",
    "selfService" : "boolean",
    "loginRedirectUrl" : "string"
  },
  "credentials" : {
    "userNameTemplate" : {
      "template" : "string",
      "suffix" : "string",
      "type" : "string"
    },
    "signing" : {
      "nextRotation" : "date-time",
      "kid" : "string",
      "rotationMode" : "string",
      "lastRotated" : "date-time"
    }
  },
  "created" : "date-time",
  "profile" : "object",
  "signOnMode" : "string. Possible values: BOOKMARK | BASIC_AUTH | BROWSER_PLUGIN | SECURE_PASSWORD_STORE | AUTO_LOGIN | WS_FEDERATION | SAML_2_0 | OPENID_CONNECT | SAML_1_1",
  "label" : "string",
  "features" : [ "string" ],
  "lastUpdated" : "date-time",
  "_embedded" : "object",
  "name" : "string",
  "id" : "string",
  "licensing" : {
    "seatCount" : "integer"
  },
  "status" : "string. Possible values: ACTIVE | INACTIVE | DELETED"
}

activate#

Executes activation lifecycle operation when creating the app

Type: boolean

create_application_group_assignment#

Assigns a group to an application

Parameters

appId (required)#

Type: string

groupId (required)#

Type: string

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "_embedded" : "object",
  "_links" : "object",
  "profile" : "object",
  "id" : "string",
  "priority" : "integer"
}

create_group#

Adds a new group with OKTA_GROUP type to your organization.

Parameters

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "_embedded" : "object",
  "_links" : "object",
  "lastMembershipUpdated" : "date-time",
  "created" : "date-time",
  "profile" : {
    "name" : "string",
    "description" : "string"
  },
  "objectClass" : [ "string" ],
  "id" : "string",
  "type" : "string"
}

create_policy#

Parameters

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "system" : "boolean",
  "_embedded" : "object",
  "_links" : "object",
  "created" : "date-time",
  "name" : "string",
  "description" : "string",
  "id" : "string",
  "priority" : "integer",
  "type" : "string. Possible values: OAUTH_AUTHORIZATION_POLICY | OKTA_SIGN_ON | PASSWORD",
  "status" : "string. Possible values: ACTIVE | INACTIVE"
}

activate#

Type: boolean

create_rule#

Creates a group rule to dynamically add users to the specified group if they match the condition

Parameters

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "_embedded" : "object",
  "created" : "date-time",
  "name" : "string",
  "id" : "string",
  "conditions" : {
    "expression" : {
      "type" : "string",
      "value" : "string"
    },
    "people" : {
      "groups" : {
        "include" : [ "string" ],
        "exclude" : [ "string" ]
      },
      "users" : {
        "include" : [ "string" ],
        "exclude" : [ "string" ]
      }
    }
  },
  "type" : "string",
  "actions" : {
    "assignUserToGroups" : {
      "groupIds" : [ "string" ]
    }
  },
  "allGroupsValid" : "boolean",
  "status" : "string. Possible values: ACTIVE | INACTIVE | INVALID"
}

create_session#

Creates a new session for a user with a valid session token. Use this API if, for example, you want to set the session cookie yourself instead of allowing Okta to set it, or want to hold the session ID in order to delete a session via the API instead of visiting the logout URL.

Parameters

$body#

Type: object

{
  "sessionToken" : "string"
}

create_user#

Creates a new user in your Okta organization with or without credentials.

Parameters

$body#

Type: object

{
  "lastLogin" : "date-time",
  "transitioningToStatus" : "string. Possible values: STAGED | PROVISIONED | ACTIVE | RECOVERY | PASSWORD_EXPIRED | LOCKED_OUT | DEPROVISIONED | SUSPENDED",
  "_links" : "object",
  "credentials" : {
    "emails" : [ {
      "type" : "string. Possible values: PRIMARY | SECONDARY",
      "value" : "string",
      "status" : "string. Possible values: VERIFIED | UNVERIFIED"
    } ],
    "password" : {
      "value" : "password"
    },
    "provider" : {
      "name" : "string",
      "type" : "string. Possible values: ACTIVE_DIRECTORY | FEDERATION | LDAP | OKTA | SOCIAL | IMPORT"
    },
    "recovery_question" : {
      "answer" : "string",
      "question" : "string"
    }
  },
  "created" : "date-time",
  "profile" : {
    "firstName" : "string",
    "lastName" : "string",
    "mobilePhone" : "string",
    "secondEmail" : "string",
    "login" : "string",
    "email" : "string"
  },
  "lastUpdated" : "date-time",
  "passwordChanged" : "date-time",
  "_embedded" : "object",
  "statusChanged" : "date-time",
  "id" : "string",
  "activated" : "date-time",
  "status" : "UserStatus"
}

activate#

Executes activation lifecycle operation when creating the user

Type: boolean

nextLogin#

With activate=true, set nextLogin to "changePassword" to have the password be EXPIRED, so user must change it the next time they log in.

Type: string

provider#

Indicates whether to create a user with a specified authentication provider

Type: boolean

deactivate_application#

Deactivates an active application.

Parameters

appId (required)#

Type: string

deactivate_or_delete_user#

Deletes a user permanently. This operation can only be performed on users that have a DEPROVISIONED status. This action cannot be recovered!

Parameters

userId (required)#

Type: string

sendEmail#

Type: boolean

deactivate_policy#

Parameters

policyId (required)#

Type: string

deactivate_policy_rule#

Parameters

policyId (required)#

Type: string

ruleId (required)#

Type: string

deactivate_rule#

Deactivates a specific group rule by id from your organization

Parameters

ruleId (required)#

Type: string

deactivate_user#

Deactivates a user. This operation can only be performed on users that do not have a DEPROVISIONED status. Deactivation of a user is an asynchronous operation. The user will have the transitioningToStatus property with a value of DEPROVISIONED during deactivation to indicate that the user hasn't completed the asynchronous operation. The user will have a status of DEPROVISIONED when the deactivation process is complete.

Parameters

userId (required)#

Type: string

sendEmail#

Type: boolean

delete_application#

Removes an inactive application.

Parameters

appId (required)#

Type: string

delete_application_group_assignment#

Removes a group assignment from an application.

Parameters

appId (required)#

Type: string

groupId (required)#

Type: string

delete_application_user#

Removes an assignment for a user from an application.

Parameters

appId (required)#

Type: string

userId (required)#

Type: string

sendEmail#

Type: boolean

delete_factor#

Unenrolls an existing factor for the specified user, allowing the user to enroll a new factor.

Parameters

factorId (required)#

Type: string

userId (required)#

Type: string

delete_group#

Removes a group with OKTA_GROUP type from your organization.

Parameters

groupId (required)#

Type: string

delete_policy#

Parameters

policyId (required)#

Type: string

delete_policy_rule#

Parameters

policyId (required)#

Type: string

ruleId (required)#

Type: string

delete_rule#

Removes a specific group rule by id from your organization

Parameters

ruleId (required)#

Type: string

removeUsers#

Type: boolean

end_all_user_sessions#

Removes all active identity provider sessions. This forces the user to authenticate on the next operation. Optionally revokes OpenID Connect and OAuth refresh and access tokens issued to the user.

Parameters

userId (required)#

Type: string

oauthTokens#

Revoke issued OpenID Connect and OAuth refresh and access tokens

Type: boolean

end_session#

Close Session

Parameters

sessionId (required)#

Type: string

enroll_factor#

Enrolls a user with a factor assigned by their MFA Policy.Enroll Okta Security Question Factor Enroll Okta SMS Factor Enroll Okta Call Factor Enroll Okta Verify TOTP Factor Enroll Okta Verify Push Factor Enroll Google Authenticator Factor Enroll RSA SecurID Factor Enroll Symantec VIP Factor Enroll YubiKey Factor Enroll Duo Factor Enroll U2F FactorThis operation is only available for users that have not previously enrolled a factor and have transitioned to the MFA_ENROLL state.

Parameters

$body#

Type: object

{
  "provider" : "string. Possible values: OKTA | RSA | GOOGLE | SYMANTEC | DUO | YUBICO | FIDO",
  "profile" : { },
  "factorType" : "string. Possible values: push | sms | call | token | token:software:totp | token:hardware | question | web | email | u2f | webauthn | token:software | custom",
  "stateToken" : "state token for current transaction"
}

expire_password#

This operation transitions the user to the status of PASSWORD_EXPIRED so that the user is required to change their password at their next login.

Parameters

userId (required)#

Type: string

tempPassword#

Sets the user's password to a temporary password, if true

Type: boolean

forgot_password#

Starts a new password recovery transaction for a given user and issues a recovery token that can be used to reset a user's password. Self-service password reset (forgot password) must be permitted via the user's assigned password policy to use this operation.

Parameters

$body#

Type: object

{
  "relayState" : "Optional state value that is persisted for the lifetime of the recovery transaction",
  "factorType" : "Recovery factor to use for primary authentication",
  "username" : "User's non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (dade.murphy@example.com)"
}

forgot_password_by_user#

Generates a one-time token (OTT) that can be used to reset a user's password. The user will be required to validate their security question's answer when visiting the reset link. This operation can only be performed on users with a valid recovery question credential and have an ACTIVE status.

Parameters

userId (required)#

Type: string

$body#

Type: object

{
  "emails" : [ {
    "type" : "string. Possible values: PRIMARY | SECONDARY",
    "value" : "string",
    "status" : "string. Possible values: VERIFIED | UNVERIFIED"
  } ],
  "password" : {
    "value" : "password"
  },
  "provider" : {
    "name" : "string",
    "type" : "string. Possible values: ACTIVE_DIRECTORY | FEDERATION | LDAP | OKTA | SOCIAL | IMPORT"
  },
  "recovery_question" : {
    "answer" : "string",
    "question" : "string"
  }
}

sendEmail#

Type: boolean

get_application#

Fetches an application from your Okta organization by id.

Parameters

appId (required)#

Type: string

expand#

Type: string

get_application_group_assignment#

Fetches an application group assignment

Parameters

appId (required)#

Type: string

groupId (required)#

Type: string

expand#

Type: string

get_application_key#

Gets a specific application key credential by kid

Parameters

appId (required)#

Type: string

keyId (required)#

Type: string

get_application_user#

Fetches a specific user assignment for application by id.

Parameters

appId (required)#

Type: string

userId (required)#

Type: string

expand#

Type: string

get_factor#

Fetches a factor for the specified user

Parameters

factorId (required)#

Type: string

userId (required)#

Type: string

get_group#

Lists all group rules for your organization.

Parameters

groupId (required)#

Type: string

expand#

Type: string

get_logs#

The Okta System Log API provides read access to your organization’s system log. This API provides more functionality than the Events API

Parameters

after#

Type: string

filter#

Type: string

limit#

Type: integer

q#

Type: string

since#

Type: string

sortOrder#

Type: string

until#

Type: string

get_policy#

Parameters

policyId (required)#

Type: string

expand#

Type: string

get_policy_rule#

Parameters

policyId (required)#

Type: string

ruleId (required)#

Type: string

get_rule#

Fetches a specific group rule by id from your organization

Parameters

ruleId (required)#

Type: string

expand#

Type: string

get_session#

Get details about a session.

Parameters

sessionId (required)#

Type: string

get_transaction_state#

Every authentication transaction starts with primary authentication which validates a user's primary password credential. Password Policy, MFA Policy, and Sign-On Policy are evaluated during primary authentication to determine if the user's password is expired, a factor should be enrolled, or additional verification is required. The transaction state of the response depends on the user's status, group memberships and assigned policies.

Parameters

$body#

Type: object

{
  "relayState" : "Optional state value that is persisted for the lifetime of the authentication transaction",
  "password" : "User's password credential",
  "audience" : "App ID of the target app the user is signing into",
  "oldPassword" : "User's current password that is expired or about to expire",
  "options" : {
    "warnBeforePasswordExpired" : "Transitions transaction to PASSWORD_WARN state before SUCCESS if the user's password is about to expire and within their password policy warn period",
    "multiOptionalFactorEnroll" : "Transitions transaction back to MFA_ENROLL state after successful factor enrollment when additional optional factors are available for enrollment"
  },
  "context" : {
    "deviceToken" : "A globally unique ID identifying the user's client device or user agent"
  },
  "newPassword" : "New password for user",
  "stateToken" : "state token for current transaction",
  "username" : "User's non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)",
  "token" : "Token received as part of activation user request"
}

get_user#

Fetches a user from your Okta organization.

Parameters

userId (required)#

Type: string

Fetches appLinks for all direct or indirect (via group membership) assigned applications.

Parameters

userId (required)#

Type: string

showAll#

Type: boolean

list_application_group_assignments#

Enumerates group assignments for an application.

Parameters

appId (required)#

Type: string

after#

Specifies the pagination cursor for the next page of assignments

Type: string

expand#

Type: string

limit#

Specifies the number of results for a page

Type: integer

q#

Type: string

list_application_keys#

Enumerates key credentials for an application

Parameters

appId (required)#

Type: string

list_application_users#

Enumerates all assigned application users for an application.

Parameters

appId (required)#

Type: string

after#

specifies the pagination cursor for the next page of assignments

Type: string

expand#

Type: string

filter#

Type: string

limit#

specifies the number of results for a page

Type: integer

q#

Type: string

query_scope#

Type: string

list_applications#

Enumerates apps added to your organization with pagination. A subset of apps can be returned that match a supported filter expression or query.

Parameters

after#

Specifies the pagination cursor for the next page of apps

Type: string

expand#

Traverses users link relationship and optionally embeds Application User resource

Type: string

filter#

Filters apps by status, user.id, group.id or credentials.signing.kid expression

Type: string

includeNonDeleted#

Type: boolean

limit#

Specifies the number of results for a page

Type: integer

q#

Type: string

list_assigned_roles#

Lists all roles assigned to a user.

Parameters

userId (required)#

Type: string

expand#

Type: string

list_factors#

Enumerates all the enrolled factors for the specified user

Parameters

userId (required)#

Type: string

list_group_targets_for_role#

Success

Parameters

roleId (required)#

Type: string

userId (required)#

Type: string

after#

Type: string

limit#

Type: integer

list_group_users#

Enumerates all users that are a member of a group.

Parameters

groupId (required)#

Type: string

after#

Specifies the pagination cursor for the next page of users

Type: string

limit#

Specifies the number of user results in a page

Type: integer

managedBy#

Type: string

list_groups#

Enumerates groups in your organization with pagination. A subset of groups can be returned that match a supported filter expression or query.

Parameters

after#

Specifies the pagination cursor for the next page of groups

Type: string

expand#

Type: string

filter#

Filter expression for groups

Type: string

limit#

Specifies the number of group results in a page

Type: integer

q#

Searches the name property of groups for matching value

Type: string

list_policies#

Parameters

type (required)#

Type: string

after#

Type: string

expand#

Type: string

limit#

Type: integer

status#

Type: string

list_policy_rules#

Parameters

policyId (required)#

Type: string

list_rules#

Lists all group rules for your organization.

Parameters

after#

Specifies the pagination cursor for the next page of rules

Type: string

expand#

Type: string

limit#

Specifies the number of rule results in a page

Type: integer

list_supported_factors#

Enumerates all the supported factors that can be enrolled for the specified user

Parameters

userId (required)#

Type: string

list_supported_security_questions#

Enumerates all available security questions for a user's question factor

Parameters

userId (required)#

Type: string

list_user_groups#

Fetches the groups of which the user is a member.

Parameters

userId (required)#

Type: string

after#

Type: string

limit#

Type: integer

list_users#

Lists users in your organization with pagination in most cases. A subset of users can be returned that match a supported filter expression or search criteria.

Parameters

after#

Specifies the pagination cursor for the next page of users

Type: string

expand#

Type: string

filter#

Filters users with a supported expression for a subset of properties

Type: string

format#

Type: string

limit#

Specifies the number of results returned

Type: integer

q#

Finds a user that matches firstName, lastName, and email properties

Type: string

Searches for users with a supported filtering expression for most properties

Type: string

previous_transaction_state#

Moves the current transaction state back to the previous state. For example, when changing state from the start of primary authentication to MFA_ENROLL > ENROLL_ACTIVATE > OTP, the user's phone might stop working. Since the user can't see the QR code, the transaction must return to MFA_ENROLL.

Parameters

$body#

Type: object

{
  "stateToken" : "state token for a transaction"
}

primary_authentication#

Every authentication transaction starts with primary authentication which validates a user's primary password credential. Password Policy, MFA Policy, and Sign-On Policy are evaluated during primary authentication to determine if the user's password is expired, a factor should be enrolled, or additional verification is required. The transaction state of the response depends on the user's status, group memberships and assigned policies.

Parameters

$body#

Type: object

{
  "relayState" : "Optional state value that is persisted for the lifetime of the authentication transaction",
  "password" : "User's password credential",
  "audience" : "App ID of the target app the user is signing into",
  "oldPassword" : "User's current password that is expired or about to expire",
  "options" : {
    "warnBeforePasswordExpired" : "Transitions transaction to PASSWORD_WARN state before SUCCESS if the user's password is about to expire and within their password policy warn period",
    "multiOptionalFactorEnroll" : "Transitions transaction back to MFA_ENROLL state after successful factor enrollment when additional optional factors are available for enrollment"
  },
  "context" : {
    "deviceToken" : "A globally unique ID identifying the user's client device or user agent"
  },
  "newPassword" : "New password for user",
  "stateToken" : "state token for current transaction",
  "username" : "User's non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)",
  "token" : "Token received as part of activation user request"
}

refresh_session#

Refresh Session

Parameters

sessionId (required)#

Type: string

remove_group_target_from_role#

Success

Parameters

groupId (required)#

Type: string

roleId (required)#

Type: string

userId (required)#

Type: string

remove_group_user#

Removes a user from a group with OKTA_GROUP type.

Parameters

groupId (required)#

Type: string

userId (required)#

Type: string

remove_role_from_user#

Unassigns a role from a user.

Parameters

roleId (required)#

Type: string

userId (required)#

Type: string

resend_call_recovery_challenge#

Resends a Voice Call with OTP (passCode) to the user's phone

Parameters

$body#

Type: object

{
  "stateToken" : "state token for current recovery transaction"
}

resend_sms_recovery_challenge#

Resends a SMS OTP (passCode) to the user's mobile phone

Parameters

$body#

Type: object

{
  "stateToken" : "state token for current recovery transaction"
}

reset_all_factors#

This operation resets all factors for the specified user. All MFA factor enrollments returned to the unenrolled state. The user's status remains ACTIVE. This link is present only if the user is currently enrolled in one or more MFA factors.

Parameters

userId (required)#

Type: string

reset_password#

Resets a user's password to complete a recovery transaction with a PASSWORD_RESET state.

Parameters

$body#

Type: object

{
  "newPassword" : "User's new password",
  "stateToken" : "state token for current recovery transaction"
}

reset_password_by_user#

Generates a one-time token (OTT) that can be used to reset a user's password. The OTT link can be automatically emailed to the user or returned to the API caller and distributed using a custom flow.

Parameters

userId (required)#

Type: string

provider#

Type: string

sendEmail#

Type: boolean

skip_transaction_state#

Send a skip link to skip the current transaction state and advance to the next state.If the response returns a skip link, then you can advance to the next state without completing the current state (such as changing the password).
For example, after being warned that a password will soon expire, the user can skip the change password prompt
by clicking a skip link.Another example: a user has enrolled in multiple factors. After enrolling in one the user receives a skip link
to skip the other factors.This operation is only available for MFA_ENROLL or PASSWORD_WARN states when published as a link.

Parameters

$body#

Type: object

{
  "stateToken" : "state token for a transaction"
}

suspend_user#

Suspends a user. This operation can only be performed on users with an ACTIVE status. The user will have a status of SUSPENDED when the process is complete.

Parameters

userId (required)#

Type: string

unlock_account#

Starts a new unlock recovery transaction for a given user and issues a recovery token that can be used to unlock a user's account.Unlock Account with Email Factor Unlock Account with SMS Factor Unlock Account with Trusted ApplicationSelf-service unlock must be permitted via the user's assigned password policy to use this operation.

Parameters

$body#

Type: object

{
  "relayState" : "Optional state value that is persisted for the lifetime of the recovery transaction",
  "factorType" : "Recovery factor to use for primary authentication",
  "username" : "User's non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (dade.murphy@example.com)"
}

unlock_user#

Unlocks a user with a LOCKED_OUT status and returns them to ACTIVE status. Users will be able to login with their current password.

Parameters

userId (required)#

Type: string

unsuspend_user#

Unsuspends a user and returns them to the ACTIVE state. This operation can only be performed on users that have a SUSPENDED status.

Parameters

userId (required)#

Type: string

update_application#

Updates an application in your organization.

Parameters

appId (required)#

Type: string

$body#

Type: object

{
  "settings" : {
    "app" : { },
    "inlineHookId" : "string",
    "implicitAssignment" : "boolean",
    "notifications" : {
      "vpn" : {
        "helpUrl" : "string",
        "message" : "string",
        "network" : {
          "include" : [ "string" ],
          "connection" : "string",
          "exclude" : [ "string" ]
        }
      }
    }
  },
  "visibility" : {
    "hide" : {
      "web" : "boolean",
      "iOS" : "boolean"
    },
    "appLinks" : "object",
    "autoSubmitToolbar" : "boolean"
  },
  "_links" : "object",
  "accessibility" : {
    "errorRedirectUrl" : "string",
    "selfService" : "boolean",
    "loginRedirectUrl" : "string"
  },
  "credentials" : {
    "userNameTemplate" : {
      "template" : "string",
      "suffix" : "string",
      "type" : "string"
    },
    "signing" : {
      "nextRotation" : "date-time",
      "kid" : "string",
      "rotationMode" : "string",
      "lastRotated" : "date-time"
    }
  },
  "created" : "date-time",
  "profile" : "object",
  "signOnMode" : "string. Possible values: BOOKMARK | BASIC_AUTH | BROWSER_PLUGIN | SECURE_PASSWORD_STORE | AUTO_LOGIN | WS_FEDERATION | SAML_2_0 | OPENID_CONNECT | SAML_1_1",
  "label" : "string",
  "features" : [ "string" ],
  "lastUpdated" : "date-time",
  "_embedded" : "object",
  "name" : "string",
  "id" : "string",
  "licensing" : {
    "seatCount" : "integer"
  },
  "status" : "string. Possible values: ACTIVE | INACTIVE | DELETED"
}

update_application_user#

Update Application Profile for Assigned User

Parameters

appId (required)#

Type: string

userId (required)#

Type: string

$body#

Type: object

{
  "_links" : "object",
  "credentials" : {
    "password" : {
      "value" : "password"
    },
    "userName" : "string"
  },
  "created" : "date-time",
  "profile" : "object",
  "syncState" : "string",
  "externalId" : "string",
  "lastUpdated" : "date-time",
  "passwordChanged" : "date-time",
  "lastSync" : "date-time",
  "_embedded" : "object",
  "scope" : "string",
  "statusChanged" : "date-time",
  "id" : "string",
  "status" : "string"
}

update_group#

Updates the profile for a group with OKTA_GROUP type from your organization.

Parameters

groupId (required)#

Type: string

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "_embedded" : "object",
  "_links" : "object",
  "lastMembershipUpdated" : "date-time",
  "created" : "date-time",
  "profile" : {
    "name" : "string",
    "description" : "string"
  },
  "objectClass" : [ "string" ],
  "id" : "string",
  "type" : "string"
}

update_policy#

Parameters

policyId (required)#

Type: string

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "system" : "boolean",
  "_embedded" : "object",
  "_links" : "object",
  "created" : "date-time",
  "name" : "string",
  "description" : "string",
  "id" : "string",
  "priority" : "integer",
  "type" : "string. Possible values: OAUTH_AUTHORIZATION_POLICY | OKTA_SIGN_ON | PASSWORD",
  "status" : "string. Possible values: ACTIVE | INACTIVE"
}

update_policy_rule#

Parameters

policyId (required)#

Type: string

ruleId (required)#

Type: string

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "system" : "boolean",
  "created" : "date-time",
  "id" : "string",
  "priority" : "integer",
  "type" : "string. Possible values: SIGN_ON | PASSWORD",
  "status" : "string. Possible values: ACTIVE | INACTIVE"
}

update_rule#

Success

Parameters

ruleId (required)#

Type: string

$body#

Type: object

{
  "lastUpdated" : "date-time",
  "_embedded" : "object",
  "created" : "date-time",
  "name" : "string",
  "id" : "string",
  "conditions" : {
    "expression" : {
      "type" : "string",
      "value" : "string"
    },
    "people" : {
      "groups" : {
        "include" : [ "string" ],
        "exclude" : [ "string" ]
      },
      "users" : {
        "include" : [ "string" ],
        "exclude" : [ "string" ]
      }
    }
  },
  "type" : "string",
  "actions" : {
    "assignUserToGroups" : {
      "groupIds" : [ "string" ]
    }
  },
  "allGroupsValid" : "boolean",
  "status" : "string. Possible values: ACTIVE | INACTIVE | INVALID"
}

update_user#

Update a user's profile and/or credentials using strict-update semantics.

Parameters

userId (required)#

Type: string

$body#

Type: object

{
  "lastLogin" : "date-time",
  "transitioningToStatus" : "string. Possible values: STAGED | PROVISIONED | ACTIVE | RECOVERY | PASSWORD_EXPIRED | LOCKED_OUT | DEPROVISIONED | SUSPENDED",
  "_links" : "object",
  "credentials" : {
    "emails" : [ {
      "type" : "string. Possible values: PRIMARY | SECONDARY",
      "value" : "string",
      "status" : "string. Possible values: VERIFIED | UNVERIFIED"
    } ],
    "password" : {
      "value" : "password"
    },
    "provider" : {
      "name" : "string",
      "type" : "string. Possible values: ACTIVE_DIRECTORY | FEDERATION | LDAP | OKTA | SOCIAL | IMPORT"
    },
    "recovery_question" : {
      "answer" : "string",
      "question" : "string"
    }
  },
  "created" : "date-time",
  "profile" : {
    "firstName" : "string",
    "lastName" : "string",
    "mobilePhone" : "string",
    "secondEmail" : "string",
    "login" : "string",
    "email" : "string"
  },
  "lastUpdated" : "date-time",
  "passwordChanged" : "date-time",
  "_embedded" : "object",
  "statusChanged" : "date-time",
  "id" : "string",
  "activated" : "date-time",
  "status" : "UserStatus"
}

strict#

Type: boolean

verify_call_factor#

Parameters

factorId (required)#

Factor ID

Type: string

rememberDevice (required)#

user's decision to remember device

Type: boolean

$body#

Type: object

{
  "signatureData" : "base64 encoded signature data from the U2F token",
  "answer" : "answer to security question",
  "stateToken" : "state token for current transaction",
  "clientData" : "base64 encoded client data from the U2F token",
  "passCode" : "base64 encoded signature data from the U2F token"
}

autoPush#

user's decision to send push to device automatically

Type: boolean

verify_call_recovery_factor#

Verifies a Voice Call OTP (passCode) sent to the user's device for primary authentication for a recovery transaction with RECOVERY_CHALLENGE status.

Parameters

$body#

Type: object

{
  "stateToken" : "state token for current recovery transaction",
  "passCode" : "Passcode received via the voice call"
}

verify_factor#

Parameters

factorId (required)#

Factor ID

Type: string

rememberDevice (required)#

user's decision to remember device

Type: boolean

$body#

Type: object

{
  "signatureData" : "base64 encoded signature data from the U2F token",
  "answer" : "answer to security question",
  "stateToken" : "state token for current transaction",
  "clientData" : "base64 encoded client data from the U2F token",
  "passCode" : "base64 encoded signature data from the U2F token"
}

autoPush#

user's decision to send push to device automatically

Type: boolean

verify_factor_by_user#

Verifies an OTP for a token or token:hardware factor

Parameters

factorId (required)#

Type: string

userId (required)#

Type: string

$body#

Type: object

{
  "answer" : "string",
  "nextPassCode" : "string",
  "tokenLifetimeSeconds" : "integer",
  "passCode" : "string",
  "activationToken" : "string"
}

User-Agent#

Type: string

X-Forwarded-For#

Type: string

templateId#

Type: string

tokenLifetimeSeconds#

Type: integer

verify_push_factor#

Parameters

factorId (required)#

Factor ID

Type: string

rememberDevice (required)#

user's decision to remember device

Type: boolean

$body#

Type: object

{
  "signatureData" : "base64 encoded signature data from the U2F token",
  "answer" : "answer to security question",
  "stateToken" : "state token for current transaction",
  "clientData" : "base64 encoded client data from the U2F token",
  "passCode" : "base64 encoded signature data from the U2F token"
}

autoPush#

user's decision to send push to device automatically

Type: boolean

verify_recovery_token#

Validates a recovery token that was distributed to the end user to continue the recovery transaction.

Parameters

$body#

Type: object

{
  "recoveryToken" : "Recovery token that was distributed to the end user via out-of-band mechanism such as email"
}

verify_security_question_factor#

Parameters

factorId (required)#

Factor ID

Type: string

rememberDevice (required)#

user's decision to remember device

Type: boolean

$body#

Type: object

{
  "signatureData" : "base64 encoded signature data from the U2F token",
  "answer" : "answer to security question",
  "stateToken" : "state token for current transaction",
  "clientData" : "base64 encoded client data from the U2F token",
  "passCode" : "base64 encoded signature data from the U2F token"
}

autoPush#

user's decision to send push to device automatically

Type: boolean

verify_sms_factor#

Parameters

factorId (required)#

Factor ID

Type: string

rememberDevice (required)#

user's decision to remember device

Type: boolean

$body#

Type: object

{
  "signatureData" : "base64 encoded signature data from the U2F token",
  "answer" : "answer to security question",
  "stateToken" : "state token for current transaction",
  "clientData" : "base64 encoded client data from the U2F token",
  "passCode" : "base64 encoded signature data from the U2F token"
}

autoPush#

user's decision to send push to device automatically

Type: boolean

verify_sms_recovery_factor#

Verifies a SMS OTP (passCode) sent to the user's mobile phone for primary authentication for a recovery transaction with RECOVERY_CHALLENGE status.

Parameters

$body#

Type: object

{
  "stateToken" : "state token for current recovery transaction",
  "passCode" : "OTP sent to device"
}

verify_totp_factor#

Parameters

factorId (required)#

Factor ID

Type: string

rememberDevice (required)#

user's decision to remember device

Type: boolean

$body#

Type: object

{
  "signatureData" : "base64 encoded signature data from the U2F token",
  "answer" : "answer to security question",
  "stateToken" : "state token for current transaction",
  "clientData" : "base64 encoded client data from the U2F token",
  "passCode" : "base64 encoded signature data from the U2F token"
}

autoPush#

user's decision to send push to device automatically

Type: boolean

verify_u2f_factor#

Parameters

factorId (required)#

Factor ID

Type: string

rememberDevice (required)#

user's decision to remember device

Type: boolean

$body#

Type: object

{
  "signatureData" : "base64 encoded signature data from the U2F token",
  "answer" : "answer to security question",
  "stateToken" : "state token for current transaction",
  "clientData" : "base64 encoded client data from the U2F token",
  "passCode" : "base64 encoded signature data from the U2F token"
}

autoPush#

user's decision to send push to device automatically

Type: boolean