The OTP API from 1Kosmos — 3 operation(s) for otp.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/1kosmos-otp-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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.
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
This 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.
Request
Method: POST
URL: {{client_api}}/api/r2/otp/verify
Request Body Parameters
The request body must be sent in JSON format and should include the following parameters:
Field Name
Required Field
Type
Description
code
Yes
string
The OTP code that the user has received and is attempting to verify.
userId
Yes
string
The same unique identifier used to generate the OTP.
userPublicKey
No
string
The public key associated with the user, used for cryptographic verification.
communityId
Yes
string
The identifier for the community to which the user belongs.
tenantId
Yes
string
The identifier for the tenant associated with the community.
serviceName
No
string
Name of the service for which OTP is being verified
Response
The response will be returned in JSON format. The structure of the response may include:
Field Name
Type
Description
error_code
integer
A code representing the status of the request. A value of 0 typically indicates no error.
message
string
A message providing additional information about the request status. This may be empty or contain relevant info.
status
boolean
Indicates whether the OTP verification was successful or not.
Example Response
{
"error_code": 0,
"message": "",
"status": true
}
Error Response
HTTP Status
Error Message
Description
403
OTP request locked for the user.
Too many wrong OTPs & tries a new OTP
410
OTP match found, but the validity time has expired
Expired OTP
404
Invalid OTP
Wrong OTP
400
Unable to load tenant/community
Incorrect tenant/community
409
OTP already used
OTP already used
410
OTP match found, but the validity time has expired.
OTP match found, but the validity time has expired.
Additional Notes
A 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.
Ensure that the OTP code is valid and has not expired before making the request.
The response may vary based on the success or failure of the verification process.
This 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
This 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.
Request
Method: POST
URL: {{client_api}}/api/r3/otp/verify
Request Body Parameters
The request body must be sent in JSON format and should include the following parameters:
Field Name
Required Field
Type
Description
code
Yes
string
The OTP code that the user has received and is attempting to verify.
userId
Yes
string
The same unique identifier used to generate the OTP.
userPublicKey
No
string
The public key associated with the user, used for cryptographic verification.
communityId
Yes
string
The identifier for the community to which the user belongs.
tenantId
Yes
string
The identifier for the tenant associated with the community.
serviceName
No
string
Name of the service for which OTP is being verified
Response
The response will be returned in JSON format. The structure of the response may include:
Field Name
Type
Description
error_code
integer
A code representing the status of the request. A value of 0 typically indicates no error.
error_message
string
A message providing additional information about the request status. This may be empty or contain relevant info.
message
string
A message providing additional information about the request status. This may be empty or contain relevant info.
status
boolean
Indicates whether the OTP verification was successful or not.
Example Response
{
"error_code": 0,
"error_maessage": "",
"message": "",
"status": true
}
Error Response
HTTP Status
Error Code
Error Message
Description
400
E10001
Invalid OTP
Wrong OTP
400
E10002
OTP already used
OTP already used
400
E10003
OTP match found, but the validity time has expired
Expired OTP
400
E11001
OTP request locked for the user.
Too many wrong OTPs & user account is locked.
400
E20001
Unable to load tenant/community
Incorrect tenant/community
401
E20002
Invalid License key
License key used is not authorized
Additional Notes
Ensure that the OTP code is valid and has not expired before making the request.
The response may vary based on the success or failure of the verification process.
This 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.