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