> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Creates and returns an OTP

`POST /api/web/v1/otps`

Create and return an OTP. Caller requires the OTPS:ADD permission.

## Request Body

Required.

### application/json

Schema

```json
{
  "required": [
    "applicationId",
    "userId"
  ],
  "type": "object",
  "properties": {
    "applicationId": {
      "type": "string",
      "description": "Unique identifier of the Identity as a Service Authentication API application",
      "example": "6781549d-433c-44ea-a42f-4705c26f3245"
    },
    "clientIp": {
      "type": "string",
      "description": "Provided client IP address."
    },
    "deliverOTP": {
      "type": "boolean",
      "description": "Whether to deliver the OTP.  If not specified, this defaults to true."
    },
    "otpDeliveryType": {
      "type": "string",
      "description": "Defines how a user receives their one-time passcode (Email, Text message (SMS), or Voice message (VOICE)).",
      "example": "EMAIL/SMS/VOICE",
      "enum": [
        "EMAIL",
        "SMS",
        "VOICE",
        "WECHAT",
        "WHATSAPP"
      ]
    },
    "returnOTP": {
      "type": "boolean",
      "description": "Whether to return the OTP.  If not specified, this defaults to false."
    },
    "transactionDetails": {
      "type": "array",
      "description": "Defines transaction details to be associated with the OTP.",
      "items": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "description": "The transaction detail name.",
            "example": "Amount"
          },
          "usage": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "The transaction detail usage. If not provided, the attribute supports all usages. RBA indicates that the detail is used for risk-based authentication; TVS indicates that the detail is used for transaction verification.",
              "example": "RBA",
              "enum": [
                "RBA",
                "TVS"
              ]
            }
          },
          "value": {
            "type": "string",
            "description": "The transaction detail value.",
            "example": "$10,001"
          }
        },
        "description": "Transaction detail item and its value used with push authenticators and with offline transaction verification.",
        "title": "TransactionDetail"
      }
    },
    "userId": {
      "type": "string",
      "description": "User ID (containing the user ID or a user alias) of the Identity as a Service user the OTP is being created for.",
      "example": "alice"
    }
  },
  "description": "The OTP to create.",
  "title": "OTPCreateParms"
}
```

## Responses

### 200

Successful

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "exp": {
      "type": "integer",
      "description": "The authorization token expiry time.",
      "format": "int64"
    },
    "otp": {
      "type": "string",
      "description": "The OTP."
    },
    "otpDeliveryType": {
      "type": "string",
      "description": "The OTP delivery type used.  The value is null if OTP delivery was not performed",
      "enum": [
        "EMAIL",
        "SMS",
        "VOICE",
        "WECHAT",
        "WHATSAPP"
      ]
    },
    "otpExpiryDate": {
      "type": "string",
      "description": "The OTP Expiry Date.",
      "format": "date-time",
      "example": "2019-02-19T13:17:27Z"
    },
    "token": {
      "type": "string",
      "description": "The authorization token representing the OTP authentication challenge to complete."
    }
  },
  "description": "An OTP  defines the information returned about an OTP.",
  "title": "OTP"
}
```

### 400

Bad Request

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 401

Access denied

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 403

Forbidden

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 404

Not Found

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 409

Conflict

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

## Security

Requirements

```json
[
  {
    "AdminAPIAuthentication": [
      "OTPS:ADD"
    ]
  }
]
```