{
"openapi": "3.0.0",
"info": {
"title": "1K-Wallet Service",
"version": "1.10.10",
"license": {}
},
"paths": {
"/.well-known": {
"get": {
"summary": "Get well known config.",
"description": "Get well known config
\n\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns an object\n",
"tags": [
"Well Known config"
],
"responses": {
"200": {
"description": "Success\n\n```\n{\n \"auth_endpoint\": \"https://$dns/walletapi/authenticate\",\n \"enrollment_check_endpoint\": \"https://$dns/walletapi/check_enrollment\",\n \"public_key\": \"string\" //same as /publickeys endpoint,\n \"purpose_supported\": [\"authenticate\", \"enroll\"],\n \"scopes_supported\": [\"wallet\", \"liveness_score\", \"selfie\", \"face_compare_score\"]\n}\n```\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WellKnowResponse"
}
}
}
}
}
}
},
"/webhooks/{uwl_session_id}": {
"post": {
"summary": "[DEPRECATED] PID webhook callback for UWL session",
"description": "**DEPRECATED**: This endpoint is deprecated and has been removed. Use /v2/submit_face instead.\n\nSunset date: 2026-02-02\n",
"deprecated": true,
"tags": [
"Wallet"
],
"parameters": [
{
"in": "path",
"name": "uwl_session_id",
"required": true,
"schema": {
"type": "string"
},
"description": "UWL session ID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"description": "PID session ID"
},
"transactionID": {
"type": "string",
"description": "Transaction ID"
},
"status": {
"type": "string",
"description": "Status of the PID session",
"enum": [
"SUCCESS"
]
},
"puid": {
"type": "string"
},
"guid": {
"type": "string"
},
"selfie": {
"type": "string",
"description": "Base64 encoded selfie image (if required)"
},
"message": {
"type": "string",
"description": "Message for the PID session"
}
}
}
}
}
},
"security": [
{
"authorization": []
}
],
"responses": {
"410": {
"description": "Gone - This endpoint has been deprecated",
"headers": {
"Deprecation": {
"description": "Indicates the endpoint is deprecated",
"schema": {
"type": "string"
}
},
"Sunset": {
"description": "Date when the endpoint will be removed",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"sunset": {
"type": "string"
}
}
}
}
}
}
}
}
},
"/verify_pin": {
"post": {
"summary": "Verify user PIN for authentication",
"description": "Verifies the user PIN and device trust, returns isAuthenticated in encrypted response.\n\n| **Headers** |\n|----------------------------------------------|\n\n### authorization (required)\nAuthorization token\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n| **Request Body** |\n|----------------------------------------------|\n\n### data (required)\nECDSA encrypted payload with pin and isTrustedDevice\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns isAuthenticated in encrypted response.\nThis API throws an error if something goes wrong.\n",
"tags": [
"Wallet"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"authorization": []
}
],
"parameters": [
{
"name": "authorization",
"in": "header",
"description": "Authorization token",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "requestid",
"in": "header",
"description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "publickey",
"in": "header",
"description": "Public Key / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"requestBody": {
"description": "Request body contains below fields to verify PIN.\n```\n{\n \"data\": {\n \"pin\": \"1234\",\n \"isTrustedDevice\": true\n }\n}\n```\n",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"pin": {
"type": "string",
"description": "pin"
},
"isTrustedDevice": {
"type": "boolean",
"description": "Indicates if the device is trusted"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "string",
"description": "ECDSA encrypted response with token { isAuthenticated }"
}
}
}
}
}
},
"400": {
"description": "Bad Request, Validation errors."
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Session not found"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/userDeviceInfo": {
"post": {
"summary": "Add User-Device Info into Login Attemp DB",
"description": "Add User-Device Info into Login Attemp DB\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n\n### sessionId (required)\nsessionId\n\n### deviceInfo (optional)\ndeviceInfo\n\n### userInfo (optional)\nuserInfo\n\n| **Returns** |\n|-------------------------------------------|\n",
"tags": [
"Wallet"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
}
],
"requestBody": {
"description": "\n```\n\"data\": {\n \"sessionId\": \"\",\n \"deviceInfo\": \"\",\n \"userInfo\": \"\"\n},\n\"publicKey\": \"\"\n```\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddUserDeviceInfoRequest"
}
}
}
},
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddUserDeviceInfoResponse"
}
}
}
},
"400": {
"description": "Bad Request, Validation errors."
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/session_result": {
"post": {
"summary": "Get session result by UWL session ID",
"description": "Fetches session_info using uwl_session_id and returns success, failure, or pending status. Allows deviceId in request body.",
"tags": [
"Wallet"
],
"security": [
{
"keyId": []
}
],
"parameters": [
{
"name": "session",
"in": "query",
"required": true,
"description": "UWL session ID",
"schema": {
"type": "string"
}
},
{
"name": "publickey",
"in": "header",
"description": "Public Key / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deviceId": {
"type": "string",
"description": "Device ID to check device trust"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Session result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"failure",
"pending",
"pin_required"
]
},
"message": {
"type": "string"
}
}
}
}
}
},
"400": {
"description": "Missing session parameter"
},
"404": {
"description": "Session not found"
}
}
}
},
"/servicekeys": {
"get": {
"summary": "Get service keys",
"description": "This endpoint returns available service keys.\nThe license you are using must be of authLevel 'system'\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns array with service keys\n",
"tags": [
"Service Key"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"license": []
}
],
"parameters": [
{
"name": "requestid",
"in": "header",
"description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "publickey",
"in": "header",
"description": "Public Key / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "licensekey",
"in": "header",
"description": "License key encrypted with ECDSA / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServiceKeysResponse"
}
}
}
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/servicekey/{keyId}": {
"delete": {
"summary": "Reset Service Key",
"description": "This endpoint resets service key for given keyId. Deletes current one and recreates a new one.\nThe license you are using must be of authLevel 'system'\n\n| **Parameters** |\n|----------------------------------------------|\n\n### keyId (required)\nThe keyId of service key to reset\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns re-created service key\n",
"tags": [
"Service Key"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"license": []
}
],
"parameters": [
{
"name": "keyId",
"in": "path",
"description": "keyId of service key to reset",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "requestid",
"in": "header",
"description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "publickey",
"in": "header",
"description": "Public Key / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "licensekey",
"in": "header",
"description": "License key encrypted with ECDSA / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServiceKeysResponse"
}
}
}
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "Unauthorized"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/sd": {
"get": {
"summary": "Get all service directories.",
"description": "Get all service directories.\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns all service directories.\n",
"tags": [
"Service Directory"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetServiceComponentsResponse"
}
}
}
}
}
}
},
"/publickeys": {
"get": {
"summary": "Get system's public key.",
"description": "Get system's public key.\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns a public key object\n",
"tags": [
"Public Key"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicKeyResponse"
}
}
}
},
"401": {
"description": "Invalid ECDSA signature / ID found."
}
}
}
},
"/identify_selfie": {
"post": {
"summary": "Identify selfie using dvcId to get a faceKey",
"description": "Accepts a selfie image, dvcId, communityId and tenantId. Fetches the verification config and verifier\nfrom docuverify, performs face search.\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds\n\n### publickey (required)\nPublic key\n\n| **Request Body** |\n|----------------------------------------------|\n\n### data (required)\nECDSA encrypted payload containing selfie, dvcId, communityId and tenantId\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns faceKey (sha512 hash of the matched faceId) in encrypted response.\n",
"tags": [
"Wallet"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"license": []
}
],
"parameters": [
{
"name": "licensekey",
"in": "header",
"description": "License key encrypted with ECDSA / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "requestid",
"in": "header",
"description": "JSON string encrypted with ECDSA / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "publickey",
"in": "header",
"description": "Public Key / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"requestBody": {
"description": "Request body contains selfie, dvcId, communityId, tenantId and optionally dns.\n```\n{\n \"data\": {\n \"selfie\": \"base64_encoded_selfie_image\",\n \"dvcId\": \"device_verification_config_id_or_tag\",\n \"communityId\": \"community_id\",\n \"tenantId\": \"tenant_id\",\n \"dns\": \"optional_community_dns_url\"\n }\n}\n```\n",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"selfie": {
"type": "string",
"description": "Base64 encoded selfie image"
},
"dvcId": {
"type": "string",
"description": "Device verification config ID or tag"
},
"communityId": {
"type": "string",
"description": "Community ID associated with the dvcId"
},
"tenantId": {
"type": "string",
"description": "Tenant ID associated with the community"
},
"dns": {
"type": "string",
"description": "(Optional) Community DNS URL for fetching secondary verifier config from CaaS. Falls back to local CaaS if not provided."
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "string",
"description": "ECDSA encrypted response containing faceKey (sha512 hash of matched faceId)"
},
"publicKey": {
"type": "string",
"description": "Service public key"
}
}
}
}
}
},
"400": {
"description": "Bad Request, Validation errors or verification config/verifier not found."
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Face not found in selfie"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/healthz": {
"get": {
"summary": "Get healthz.",
"description": "Get healthz
\n\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns a healthz object\n - ```version = ..```
\n\n - ```git-tag```: When code is compiled from a git-tag, this must carry the tag name. This should match one of the git tags.\n - ```commit-id```: This is the git-commit-id. eg: When code is built from this, the hex code, in the end, is the commit it.\n - ```dob```: Date Of Build. This is epoc-time-in-se\tconds that tell the time when the build was created.\n - \u200bif the code is not built from a git-tag, then the ```version =\ufffc.```\n",
"tags": [
"Healthz"
],
"responses": {
"200": {
"description": "Success\n\n```\n{\n \"status\": \"all services operational\",\n \"publicKey\": \"string\" //same as /publickeys endpoint,\n \"code\": \"200\",\n \"version\": \"\" //as defined above\n}\n```\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HealthzResponse"
}
}
}
}
}
}
},
"/environment": {
"get": {
"description": "Provide details regarding the environments.\n| **Returns** |\n|-------------------------------------------|\n\nReturns an environment object\n",
"tags": [
"Environment"
],
"security": [
{
"license": []
}
],
"responses": {
"200": {
"description": "Success"
}
}
}
},
"/ecdsa_helper/{method}": {
"post": {
"summary": "Encrypt and decrypt the data string by public key and private key.",
"description": "Encrypt and decrypt the data string by public key and private key.\n\n| **Parameters** |\n|----------------------------------------------|\n\n### method (optional)\nThe method parameter is type of enum. Default value is encrypt.
\nThis parameter only accepts following values
\n **encrypt**, **decrypt**\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n\n### data (optional)\nThe data key is type of String.\n\n
\n### publicKey (required)\nThe publicKey is type of string.\n\n
\n### privateKey (required)\nThe privateKey is type of string.\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns the encrypted/decrypted string.
\nThis API throw an error if something goes wrong. A common source of error is public or private key is not valid.\n",
"tags": [
"ECDSA Helper"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EcdsaEncryptDecryptRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "method",
"schema": {
"type": "string",
"enum": [
"encrypt",
"decrypt"
],
"default": "encrypt"
}
}
],
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EcdsaEncryptDecryptResponse"
}
}
}
}
}
}
},
"/check_enrollment": {
"post": {
"summary": "Check user enrollment of wallet",
"description": "Check user enrollment of wallet\n- any valid license key\n- Atleast 1 entry in list is required\n- Either DID or PublicKey or BOTH can be provided.\n- Any time both are provided, that a single record in DB must match both did and publicKey in order to call it a \"MATCH\"\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n| **Request Body** |\n|----------------------------------------------|\n\n\n### list (required)\nlist of user's did and publicKey\n\n| **Returns** |\n|-------------------------------------------|\n",
"tags": [
"Wallet"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"license": []
}
],
"parameters": [
{
"name": "licensekey",
"in": "header",
"description": "License key encrypted with ECDSA / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "requestid",
"in": "header",
"description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "publickey",
"in": "header",
"description": "Public Key / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"requestBody": {
"description": "\n```\n{\n \"list\": [{\"did\": string}, {\"publicKey\": string}, {\"did\": string, \"publicKey\": string}]\n}\n```\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckEnrollmentRequest"
}
}
}
},
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckEnrollmentResponse"
}
}
}
},
"400": {
"description": "Bad Request, Validation errors."
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/authenticate_with_liveid": {
"post": {
"summary": "[DEPRECATED] Authenticate with LiveID[V2 CP]",
"description": "**DEPRECATED**: This endpoint is deprecated and has been removed. Use /v2/authenticate_with_liveid instead.\n\nSunset date: 2026-02-02\n",
"deprecated": true,
"tags": [
"Wallet"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"license": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Request body no longer accepted - endpoint deprecated"
}
}
}
},
"responses": {
"410": {
"description": "Gone - This endpoint has been deprecated",
"headers": {
"Deprecation": {
"description": "Indicates the endpoint is deprecated",
"schema": {
"type": "string"
}
},
"Sunset": {
"description": "Date when the endpoint will be removed",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"sunset": {
"type": "string"
}
}
}
}
}
}
}
}
},
"/authenticate": {
"get": {
"summary": "[DEPRECATED] Fetch sessionInfo and store into DB, then redirect to authentication page",
"description": "**DEPRECATED**: This endpoint is deprecated and has been removed. Use /v2/authenticate instead.\n\nSunset date: 2026-02-02\n",
"deprecated": true,
"tags": [
"Wallet"
],
"parameters": [
{
"name": "session",
"in": "query",
"required": true,
"description": "Base64 encoded session URL",
"schema": {
"type": "string"
}
}
],
"responses": {
"410": {
"description": "Gone - This endpoint has been deprecated",
"headers": {
"Deprecation": {
"description": "Indicates the endpoint is deprecated",
"schema": {
"type": "string"
}
},
"Sunset": {
"description": "Date when the endpoint will be removed",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"sunset": {
"type": "string"
}
}
}
}
}
}
}
}
},
"/v2/submit_face": {
"post": {
"summary": "Submit face for verification and enrolling",
"description": "Submits a selfie for face verification and enrolling.
\n\n| **Headers** |\n|----------------------------------------------|\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n| **Request Body** |\n|----------------------------------------------|\n\n### sessionId (required)\nSession ID\n\n### selfie (required)\nBase64 encoded selfie image\n\n### deviceId (required)\nDevice ID\n\n### cameraIndicator (optional)\nCamera indicator object containing various metrics related to the camera and environment\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns session status, pin requirement, and message.
\nThis API throws an error if something goes wrong.\n",
"tags": [
"Wallet"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
}
],
"parameters": [
{
"name": "requestid",
"in": "header",
"description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "publickey",
"in": "header",
"description": "Public Key / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"requestBody": {
"description": "Request body contains below fields to submit face.\n```\n{\n \"data\": {\n \"sessionId\": \"session-123\",\n \"selfie\": \"base64string...\",\n \"deviceId\": \"device-456\",\n \"cameraIndicator\": {\n \"overallConfidence\": 0.09,\n \"riskLevel\": \"LOW\",\n \"label\": \"facetime hd camera (c4e1:9bfb)\",\n \"detectionTiers\": {},\n \"recommendations\": [],\n \"browserCompatibility\": {}\n }\n}\n```\n",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"description": "Session ID"
},
"selfie": {
"type": "string",
"description": "Base64 encoded selfie image"
},
"deviceId": {
"type": "string",
"description": "Device ID"
},
"cameraIndicator": {
"type": "object",
"description": "Camera indicator object containing various metrics related to the camera and environment"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"sessionId": {
"type": "string"
},
"status": {
"type": "string"
},
"pinRequired": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request, Validation errors."
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Session not found"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/v2/authenticate_with_liveid": {
"post": {
"summary": "Authenticate with LiveID [V2 CP].",
"description": "Authenticate with LiveID [V2 CP].\n",
"tags": [
"Wallet"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"license": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticateLiveidV2Request"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticateLiveidResponse"
}
}
}
}
}
}
},
"/v2/authenticate": {
"get": {
"summary": "Fetch sessionInfo and store into DB, then redirect to v2 authentication page",
"description": "Fetches sessionInfo, stores it in the DB, extracts dvcID from privateInfo, retrieves verification config including selfieCaptureMode, and redirects the user to the v2 authentication page with session data.",
"tags": [
"Wallet"
],
"parameters": [
{
"name": "session",
"in": "query",
"required": true,
"description": "Base64 encoded session URL",
"schema": {
"type": "string"
}
}
],
"responses": {
"302": {
"description": "Redirects to the authentication page https://${dns}/wallet/v2/authenticate with base64 encoded session data containing sessionId and selfieCaptureMode",
"headers": {
"Location": {
"description": "URL to redirect the user with session parameter containing base64 encoded JSON object with sessionId and selfieCaptureMode (auto or manualWithFaceDetection)",
"schema": {
"type": "string",
"example": "https://example.com/wallet/v2/authenticate?session=eyJzZXNzaW9uSWQiOiJhYmMxMjMiLCJzZWxmaWVDYXB0dXJlTW9kZSI6ImF1dG8ifQ=="
}
}
}
},
"400": {
"description": "Bad request - Session context not found"
},
"401": {
"description": "Unauthorized - dvcID config not found or error fetching config"
},
"404": {
"description": "Not found"
}
}
}
}
},
"components": {
"schemas": {
"PublicKeyResponse": {
"type": "object",
"properties": {
"publicKey": {
"type": "string"
}
},
"example": {
"publicKey": ""
}
},
"HealthzResponse": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"publicKey": {
"type": "string"
},
"code": {
"type": "string"
},
"version": {
"type": "string"
}
},
"example": {
"status": "all services operational",
"publicKey": "//same as /publickeys endpoint",
"code": "200",
"version": "xxxx.xxxx.xxxx"
}
},
"WellKnowResponse": {
"type": "object",
"properties": {
"auth_endpoint": {
"type": "string"
},
"enrollment_check_endpoint": {
"type": "string"
},
"public_key": {
"type": "string"
},
"purpose_supported": {
"type": "array"
},
"scopes_supported": {
"type": "array"
}
},
"example": {
"auth_endpoint": "https://$dns/walletapi/authenticate",
"enrollment_check_endpoint": "https://$dns/walletapi/check_enrollment",
"public_key": "//same as /publickeys endpoint",
"purpose_supported": [
"authenticate",
"enroll"
],
"scopes_supported": [
"wallet",
"liveness_score",
"selfie",
"face_compare_score"
]
}
},
"EcdsaEncryptDecryptRequest": {
"type": "object",
"properties": {
"data": {
"type": "string"
},
"publicKey": {
"type": "string"
},
"privateKey": {
"type": "string"
}
},
"example": {
"data": "Hey, This is example data string.",
"publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=",
"privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="
}
},
"EcdsaEncryptDecryptResponse": {
"type": "string",
"example": "xxxxxxxxxxxxxxxxxxxxxx"
},
"GetServiceComponentsResponse": {
"type": "object",
"properties": {
"name1": {
"type": "string"
},
"name2": {
"type": "string"
},
"name3": {
"type": "string"
}
},
"example": {
"name1": "https://xxx.xxxxxx.xxx/xxxxx",
"name2": "https://xxx.xxxxxx.xxx/xxxxx",
"name3": "https://xxx.xxxxxx.xxx/xxxxx"
}
},
"ServiceKeysResponse": {
"type": "array",
"description": "Service keys array",
"items": {
"type": "object",
"required": [
"tag",
"keyId",
"keySecret",
"type",
"debug"
],
"properties": {
"tag": {
"type": "string",
"description": "service ecdsa"
},
"keyId": {
"type": "string",
"description": "ecdsa publicKey"
},
"keySecret": {
"type": "string",
"description": "ecdsa private key"
},
"type": {
"type": "string",
"description": "default = ecdsa | hawk"
},
"debug": {
"type": "boolean",
"description": "debug mode"
}
},
"example": {
"tag": "xxxxx",
"keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
"keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
"type": "xxxxx",
"debug": false
}
}
},
"UpdateCredentialRequest": {
"type": "object",
"properties": {
"keyId": {
"type": "string"
},
"keySecret": {
"type": "string"
},
"debug": {
"type": "boolean"
}
},
"example": {
"keyId": "xxxxx",
"keySecret": "xxxxx",
"debug": false
}
},
"CheckEnrollmentRequest": {
"type": "object",
"properties": {
"list": {
"type": "array",
"items": {
"properties": {
"did": {
"type": "string"
},
"publicKey": {
"type": "string"
}
}
}
}
},
"example": {
"list": [
{
"did": "xxxx",
"publicKey": "xxxx"
}
]
}
},
"CheckEnrollmentResponse": {
"type": "object",
"properties": {
"list": {
"type": "array",
"items": {
"properties": {
"did": {
"type": "string"
},
"publicKey": {
"type": "string"
},
"createdTS": {
"type": "date"
}
}
}
}
},
"example": {
"list": [
{
"did": "xxxxxxxxxxx",
"publicKey": "xxxxxxxxxxx",
"createdTS": "xxxxxxxxxxx"
}
]
}
},
"AddUserDeviceInfoRequest": {
"type": "object",
"properties": {
"sessionId": {
"type": "string"
},
"deviceInfo": {
"type": "object"
},
"userInfo": {
"type": "object"
}
},
"example": {
"sessionId": "xxxx",
"deviceInfo": {},
"userInfo": {}
}
},
"AddUserDeviceInfoResponse": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"AuthenticateLiveidResponse": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "success"
},
"message": {
"type": "string",
"example": "Authentication successful"
},
"data": {
"type": "object"
}
}
},
"AuthenticateLiveidV2Request": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenantId": {
"type": "string"
},
"communityId": {
"type": "string"
},
"dns": {
"type": "string"
},
"dvcID": {
"type": "string"
},
"context": {
"type": "string"
},
"userAgent": {
"type": "string"
},
"purpose": {
"type": "string"
},
"scopes": {
"type": "string",
"default": "liveness_score",
"face_compare_score": null,
"wallet": null
},
"authType": {
"type": "string",
"default": "pin"
},
"deviceInfo": {
"type": "object"
},
"userInfo": {
"type": "object"
},
"selfie": {
"type": "string"
},
"pin": {
"type": "string"
},
"user_token": {
"type": "string"
},
"isTrustedDevice": {
"type": "boolean",
"default": false
},
"skip_liveid": {
"type": "boolean",
"default": false,
"description": "If true, skips liveness check and face compare. Face search still runs. Reduces response time."
}
},
"required": [
"tenantId",
"communityId",
"dns",
"dvcID",
"context"
],
"oneOf": [
{
"required": [
"selfie"
]
},
{
"required": [
"pin",
"user_token"
]
}
]
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "error"
},
"message": {
"type": "string",
"example": "Invalid request"
}
}
},
"AuthenticateV2SessionData": {
"type": "object",
"properties": {
"sessionId": {
"type": "string",
"description": "Session identifier"
},
"selfieCaptureMode": {
"type": "string",
"enum": [
"auto",
"manualWithFaceDetection"
],
"description": "Selfie capture mode (defaults to 'auto' if not specified in dvcID config)"
}
},
"example": {
"sessionId": "abc123xyz",
"selfieCaptureMode": "auto"
}
}
},
"securitySchemes": {
"keyId": {
"type": "apiKey",
"name": "keyId",
"in": "header",
"description": "ECDSA Public Key"
},
"keySecret": {
"type": "apiKey",
"name": "keySecret",
"in": "header",
"description": "ECDSA Private Key"
},
"license": {
"type": "apiKey",
"name": "license",
"in": "header",
"description": "License key from License Microservice"
},
"authorization": {
"type": "apiKey",
"name": "authorization",
"in": "header",
"description": "authorization token for the user session"
}
}
},
"tags": [
{
"name": "Well Known config"
},
{
"name": "Wallet"
},
{
"name": "Service Key"
},
{
"name": "Public Key"
},
{
"name": "Healthz"
},
{
"name": "Environment"
},
{
"name": "ECDSA Helper"
}
],
"servers": [
{
"url": "https://pilot-root.1kosmos.net/walletapi/"
}
]
}