The OTP API from 1Kosmos — 3 operation(s) for otp.
openapi: 3.2.0
info:
title: 1Kosmos BlockID Platform OTP API
version: '2026-08-05'
description: 'REST surface of the 1Kosmos BlockID identity platform — identity verification (IDVerify), identity assurance level (IAL) lookup, one-time passcodes, user management, access codes, W3C Verifiable Credentials and Verifiable Presentations, IAL2 identity-proofing workflows, and the reporting/metrics APIs.
DERIVED, NOT PUBLISHED BY THE PROVIDER. 1Kosmos publishes no OpenAPI. This document was mechanically derived by API Evangelist from the first-party public Postman collection "1Kosmos Postman Collection" (https://documenter.getpostman.com/view/50203634/2sB3dHWZ1n), saved verbatim in this repo at postman/1kosmos-postman-collection.json. Every path, method, header, example request body and example response below is carried over from that collection; nothing was invented. Request/response schemas are typed only as generic objects because the collection carries examples, not schemas. Each operation records the original collection URL template in x-postman-request.'
contact:
name: 1Kosmos Developer Support
email: developers@1kosmos.com
url: https://developer.1kosmos.com/devportal/docs/
x-generated-by: API Evangelist enrichment pipeline (derived from Postman collection)
x-source: postman/1kosmos-postman-collection.json
servers:
- url: https://{tenantDNS}
description: Tenant-scoped BlockID host. Every 1Kosmos deployment is addressed by its own tenant DNS name; the microservice hosts the collection references as {{client_api}}, {{wf_api}} and {{reports}} are discovered at runtime from GET /caas/sd on the tenant host.
variables:
tenantDNS:
default: blockid-trial.1kosmos.net
description: Your BlockID tenant DNS name as shown in the BlockID developer dashboard. blockid-trial.1kosmos.net is the trial tenant used throughout the published docs.
security:
- licenseKey: []
publicKey: []
tags:
- name: OTP
paths:
/api/r2/otp/generate:
post:
operationId: otpGenerateOTPSMS
summary: Generate OTP - SMS
description: 'Generate OTP via SMS
This endpoint generates a One-Time Password (OTP) for a specified user within a community. The OTP can be sent via SMS based on the provided parameters.
Request
Method: POST
URL: {{client_api}}/api/r2/otp/generate
Request Body
The request body must be in JSON format and should include the following parameters:
Field Name
Required Field
Type
Description
userId
Yes
string
The unique identifier of the user. It can be User''s ID or UUID or any other transaction ID
communityId
Yes
string
The identifier of the community associated with the user.
tenantId
Yes
string
The identifier for the tenant in which the user exists.
smsTo
Yes
string
The recipient''s phone number for OTP via SMS.
smsISDCode
Yes
string
The International Subscriber Dialing code for the SMS.
smsFrom
No
string
The identifier for the source of the SMS.
smsTemplateB64
No
string
A base64 encoded template for the SMS message.
smsTemplateId
No
string
The identifier for the SMS template.
trace
No
boolean
A flag to enable or disable tracing for the request.
validitySeconds
No
integer
OTP expiration Time
serviceName
No
string
Name of the service for which OTP was generated
Response
The response will return a status code indicating the result of the OTP generation request.
Status Code: 202 (Accepted)
Content-Type: application/json
Response Body:
messageId (string): An identifier for the message sent. In this case, it may be empty.
info (string): Additional information about the request. This may also be empty.
Notes
Ensure that all parameters are provided correctly to avoid errors.
A 202 status code indicates that the request has been accepted for processing, but the processing is not yet complete.
The email and SMS templates should be properly formatted to ensure successful delivery of the OTP.
If you encounter issues, verify that the userId, communityId, tenantId, and contact details are accurate and formatted correctly.
Error Response
HTTP Status
Error Message
Description
400
This userId or userPublicKey is mandatory
Request payload without user info
400
Unable to load tenant/community
Wrong community ID or tenant ID
401
Invalid License Key
Entered License is invalid
403
OTP locked for the user
OTP locked for the user
404
Not Found
Not Found'
tags:
- OTP
parameters:
- name: requestid
in: header
required: false
schema:
type: string
description: JSON string which should contain "appid (string)", "uuid (string)" and "ts (number)" representing epoch timestamp in seconds - it should not be more or less than 60 seconds from now
- name: noecdsa
in: header
required: false
schema:
type: string
description: No Data encryption
requestBody:
required: true
content:
application/json:
schema:
type: object
examples:
Generate OTP - SMS:
value:
userId: john.doe
communityId: ''
tenantId: ''
smsTo: '919999999999'
smsISDCode: '91'
smsFrom: 1Kosmos
smsTemplateB64: ''
smsTemplateId: ''
trace: true
serviceName: 1Kosmos
validitySeconds: 120
Generate OTP - EMAIL:
value:
userId: john.doe
communityId: ''
tenantId: ''
emailFrom: test@1kosmos.com
emailSubject: Email OTP
emailTo: john.doe@1kosmos.com
emailTemplateB64: WW91ciBCbG9ja0lEIHZlcmlmaWNhdGlvbiBjb2RlIGlzOiB7e290cH19
trace: true
validitySeconds: 120
Generate OTP - Voice:
value:
userId: john.doe
communityId: ''
tenantId: ''
voiceTo: '9999999999'
voiceISDCode: '91'
voiceFrom: 1Kosmos
voiceCampaignId: ''
voiceCallTimeout: 20
voiceTemplateB64: VGhpcyBpcyBhbiBhdXRvbWF0ZWQgY2FsbCBmcm9tIDFLb3Ntb3MuIEFzIHJlcXVlc3RlZCBieSB5b3UsIHRoZSBPbmUgdGltZSBQYXNzd29yZCBpcyB7e290cH19LiBUbyByZXBlYXQsIHBsZWFzZSBwcmVzcyAxLg==
trace: true
serviceName: 1Kosmos
validitySeconds: 120
responses:
'202':
description: SMS & EMAIL OTP - Success
content:
application/json:
schema:
type: object
example:
messageId: c3db28f5-afe7-456f-973e-e77096ad68bd
info: OTP request accepted
'400':
description: No Request Body
content:
application/json:
schema:
type: object
example:
message: Unable to load tenant/community
'500':
description: Payload without Phone Mobile Number
x-postman-request: '{{client_api}}/api/r2/otp/generate'
x-postman-variants:
- Generate OTP - SMS
- Generate OTP - EMAIL
- Generate OTP - Voice
/api/r2/otp/verify:
post:
operationId: otpVerifyOTPR2
summary: Verify OTP R2
description: "Verify OTP Endpoint\nThis endpoint is used to verify a One-Time Password (OTP) submitted by a user during the authentication process. It ensures that the provided OTP corresponds to the user and is valid for the specified community and tenant.\n\nRequest\nMethod: POST\nURL: {{client_api}}/api/r2/otp/verify\n\nRequest Body Parameters\nThe request body must be sent in JSON format and should include the following parameters:\n\nField Name\nRequired Field\nType\nDescription\n\ncode\nYes\nstring\nThe OTP code that the user has received and is attempting to verify.\n\nuserId\nYes\nstring\nThe same unique identifier used to generate the OTP.\n\nuserPublicKey\nNo\nstring\nThe public key associated with the user, used for cryptographic verification.\n\ncommunityId\nYes\nstring\nThe identifier for the community to which the user belongs.\n\ntenantId\nYes\nstring\nThe identifier for the tenant associated with the community.\n\nserviceName\nNo\nstring\nName of the service for which OTP is being verified\n\nResponse\nThe response will be returned in JSON format. The structure of the response may include:\n\nField Name\nType\nDescription\n\nerror_code\ninteger\nA code representing the status of the request. A value of 0 typically indicates no error.\n\nmessage\nstring\nA message providing additional information about the request status. This may be empty or contain relevant info.\n\nstatus\nboolean\nIndicates whether the OTP verification was successful or not.\n\nExample Response\n{\n \"error_code\": 0,\n \"message\": \"\",\n \"status\": true\n}\n\nError Response\n\nHTTP Status\nError Message\nDescription\n\n403\nOTP request locked for the user.\nToo many wrong OTPs & tries a new OTP\n\n410\nOTP match found, but the validity time has expired\nExpired OTP\n\n404\nInvalid OTP\nWrong OTP\n\n400\nUnable to load tenant/community\nIncorrect tenant/community\n\n409\nOTP already used\nOTP already used\n\n410\nOTP match found, but the validity time has expired.\nOTP match found, but the validity time has expired.\n\nAdditional Notes\n\nA 404 status code indicates that the requested resource was not found. This may occur if the userId, communityId, or tenantId does not match any existing records.\n\nEnsure that the OTP code is valid and has not expired before making the request.\n\nThe response may vary based on the success or failure of the verification process.\n\nThis endpoint is crucial for maintaining secure access to user accounts by validating OTPs during the login process."
tags:
- OTP
parameters:
- name: requestid
in: header
required: false
schema:
type: string
description: JSON string which should contain "appid (string)", "uuid (string)" and "ts (number)" representing epoch timestamp in seconds - it should not be more or less than 60 seconds from now
- name: noecdsa
in: header
required: false
schema:
type: string
description: No Data encryption
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
code: '835096'
userId: john.doe
communityId: ''
tenantId: ''
responses:
'200':
description: Verify OTP - Success
content:
application/json:
schema:
type: object
example:
otp_type: user-generated
status: 'true'
'404':
description: Invalid OTP
content:
application/json:
schema:
type: object
example:
error_code: 404
message: Invalid OTP
status: false
x-postman-request: '{{client_api}}/api/r2/otp/verify'
x-postman-variants:
- Verify OTP R2
/api/r3/otp/verify:
post:
operationId: otpVerifyOTPR3
summary: Verify OTP R3
description: "Verify OTP Standardized Endpoint\nThis endpoint is used to verify a One-Time Password (OTP) submitted by a user during the authentication process. It ensures that the provided OTP corresponds to the user and is valid for the specified community and tenant with standardized success & error responses.\n\nRequest\nMethod: POST\nURL: {{client_api}}/api/r3/otp/verify\n\nRequest Body Parameters\nThe request body must be sent in JSON format and should include the following parameters:\n\nField Name\nRequired Field\nType\nDescription\n\ncode\nYes\nstring\nThe OTP code that the user has received and is attempting to verify.\n\nuserId\nYes\nstring\nThe same unique identifier used to generate the OTP.\n\nuserPublicKey\nNo\nstring\nThe public key associated with the user, used for cryptographic verification.\n\ncommunityId\nYes\nstring\nThe identifier for the community to which the user belongs.\n\ntenantId\nYes\nstring\nThe identifier for the tenant associated with the community.\n\nserviceName\nNo\nstring\nName of the service for which OTP is being verified\n\nResponse\nThe response will be returned in JSON format. The structure of the response may include:\n\nField Name\nType\nDescription\n\nerror_code\ninteger\nA code representing the status of the request. A value of 0 typically indicates no error.\n\nerror_message\nstring\nA message providing additional information about the request status. This may be empty or contain relevant info.\n\nmessage\nstring\nA message providing additional information about the request status. This may be empty or contain relevant info.\n\nstatus\nboolean\nIndicates whether the OTP verification was successful or not.\n\nExample Response\n{\n \"error_code\": 0,\n \"error_maessage\": \"\",\n \"message\": \"\",\n \"status\": true\n}\n\nError Response\n\nHTTP Status\nError Code\nError Message\nDescription\n\n400\nE10001\nInvalid OTP\nWrong OTP\n\n400\nE10002\nOTP already used\nOTP already used\n\n400\nE10003\nOTP match found, but the validity time has expired\nExpired OTP\n\n400\nE11001\nOTP request locked for the user.\nToo many wrong OTPs & user account is locked.\n\n400\nE20001\nUnable to load tenant/community\nIncorrect tenant/community\n\n401\nE20002\nInvalid License key\nLicense key used is not authorized\n\nAdditional Notes\n\nEnsure that the OTP code is valid and has not expired before making the request.\n\nThe response may vary based on the success or failure of the verification process.\n\nThis endpoint is crucial for maintaining secure access to user accounts by validating OTPs during the authentication process."
tags:
- OTP
parameters:
- name: requestid
in: header
required: false
schema:
type: string
description: JSON string which should contain "appid (string)", "uuid (string)" and "ts (number)" representing epoch timestamp in seconds - it should not be more or less than 60 seconds from now
- name: noecdsa
in: header
required: false
schema:
type: string
description: No Data encryption
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
code: '835096'
userId: john.doe
communityId: ''
tenantId: ''
responses:
'200':
description: Successful response
x-postman-request: '{{client_api}}/api/r3/otp/verify'
x-postman-variants:
- Verify OTP R3
components:
securitySchemes:
licenseKey:
type: apiKey
in: header
name: licensekey
description: The tenant/community license key, ECDSA-encrypted with the shared secret derived from the caller private key and the community public key (see BIDECDSA in the first-party helper SDKs). Sent unencrypted only when the noecdsa header is set.
publicKey:
type: apiKey
in: header
name: publickey
description: The caller ECDSA public key, used by the service to derive the shared secret that decrypts licensekey and encrypted payloads.
tenantTag:
type: apiKey
in: header
name: X-TenantTag
description: Tenant tag, required by the reports, user-management and access-code services.