---
updatedAt: 2026-05-21T16:42:54.000Z
---
# Create a one-time password verification.
Create a one-time password verification.
A new verification is created in the PENDING state. A one-time password will be available in the response body.
NB: Once a verification's state has changed from PENDING, it will cease to exist after a given time.
NB: It is recommended that this API be used with care from a secured location like a backend server.
Entitlements:
- generateOTP (Generate OTP)
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"version": "1.0.0",
"description": "Multi-factor authentication",
"title": "Multi-factor authentication"
},
"servers": [
{
"url": "https://{tenanturl}",
"variables": {
"tenanturl": {
"default": "{tenant_url}",
"description": "URL of your IBM Security Verify tenant"
}
}
}
],
"tags": [
{
"name": "One-time Password"
}
],
"paths": {
"/v2.0/factors/otp": {
"post": {
"tags": [
"One-time Password"
],
"summary": "Create a one-time password verification.",
"description": "Create a one-time password verification.
A new verification is created in the PENDING state. A one-time password will be available in the response body.
NB: Once a verification's state has changed from PENDING, it will cease to exist after a given time.
NB: It is recommended that this API be used with care from a secured location like a backend server.
Entitlements:
- generateOTP (Generate OTP)",
"operationId": "createOtpVerification_2.0",
"requestBody": {
"description": "A JSON payload that specifies the verification data.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOtpVerification_2.0"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "The verification was created.",
"headers": {
"Location": {
"description": "The URL of the newly created verification.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOtpVerificationResponse_2.0"
}
}
}
},
"400": {
"description": "The request cannot be processed because the request body contains improperly structured JSON",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequest_3"
}
}
}
},
"401": {
"description": "The unauthenticated user does not have the permissions to perform the requested operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Unauthorized_1"
}
}
}
},
"403": {
"description": "The authenticated user does not have the permissions to perform the requested operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Forbidden_2"
}
}
}
},
"501": {
"description": "Access to the requested resource is disabled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotImplemented"
}
}
}
}
},
"x-category": "Multi-factor authentication",
"x-publicAPI": "true",
"x-codegen-request-body-name": "body"
}
}
},
"components": {
"schemas": {
"CreateOtpVerification_2.0": {
"type": "object",
"properties": {
"correlation": {
"type": "string",
"description": "A value to be associated with the verification.",
"example": "4567"
},
"useEmailotpConfig": {
"type": "boolean"
},
"useSmsotpConfig": {
"type": "boolean"
}
},
"description": "The creation data for a one-time password verification."
},
"NotImplemented": {
"required": [
"messageDescription",
"messageId"
],
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "The message key identifier",
"readOnly": true,
"example": "CSIXX1234X"
},
"messageDescription": {
"type": "string",
"description": "A requester locale-specific descriptive message",
"readOnly": true,
"example": "Access to the requested resource is disabled"
}
},
"description": "The message response to the request."
},
"CreateOtpVerificationResponse_2.0": {
"required": [
"attempts",
"correlation",
"created",
"expiry",
"id",
"otp",
"retries",
"state",
"type",
"updated"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the verification",
"readOnly": true,
"example": "1e5fa156-3754-4265-8796-1a2f0a6f036f"
},
"type": {
"type": "string",
"description": "The type of authentication factor enrollment",
"readOnly": true,
"example": "otp"
},
"created": {
"type": "string",
"description": "The time when the verification was created",
"readOnly": true,
"example": "2018-07-16T02:13:47.719Z"
},
"updated": {
"type": "string",
"description": "The time when the verification was last updated",
"readOnly": true,
"example": "2018-07-16T02:13:47.719Z"
},
"expiry": {
"type": "string",
"description": "The time when the verification expires",
"readOnly": true,
"example": "2018-07-16T02:13:47.719Z"
},
"state": {
"type": "string",
"description": "The current state of the verification",
"readOnly": true,
"example": "PENDING",
"enum": [
"PENDING",
"TIMEOUT",
"CANCELED",
"FAILED",
"SUCCESS"
]
},
"updatedBy": {
"type": "string",
"description": "The identifier of the user that last updated the verification",
"readOnly": true,
"example": "50CP15KFD3"
},
"correlation": {
"type": "string",
"description": "A value to be associated with the verification",
"readOnly": true,
"example": "4567"
},
"attempts": {
"type": "integer",
"description": "The number of attempts that have been made against the verification",
"format": "int32",
"readOnly": true,
"example": 0
},
"retries": {
"type": "integer",
"description": "The maximum number of retry attempts before the verification is marked as failed",
"format": "int32",
"readOnly": true,
"example": 4
},
"otp": {
"type": "string",
"description": "The one-time password value",
"readOnly": true,
"example": "123456"
}
},
"description": "A one-time password verification."
},
"Forbidden_2": {
"required": [
"messageDescription",
"messageId"
],
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "The message key identifier",
"readOnly": true,
"example": "CSIXX1234X"
},
"messageDescription": {
"type": "string",
"description": "A requester locale-specific descriptive message",
"readOnly": true,
"example": "The access token included in the request is not valid"
}
},
"description": "The message response to the request."
},
"BadRequest_3": {
"required": [
"messageDescription",
"messageId"
],
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "The message key identifier",
"readOnly": true,
"example": "CSIXX1234X"
},
"messageDescription": {
"type": "string",
"description": "A requester locale-specific descriptive message",
"readOnly": true,
"example": "The request cannot be processed because the request body contains improperly structured JSON"
}
},
"description": "The message response to the request."
},
"Unauthorized_1": {
"required": [
"messageDescription",
"messageId"
],
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "The message key identifier",
"readOnly": true,
"example": "CSIXX1234X"
},
"messageDescription": {
"type": "string",
"description": "A requester locale-specific descriptive message",
"readOnly": true,
"example": "The unauthenticated user does not have the permissions to perform the requested operation"
}
},
"description": "The message response to the request."
}
}
},
"x-original-swagger-version": "2.0",
"x-explorer-enabled": false
}
```