Workflowsv1.00.09pilot-root.1kosmos.net/workflowapiOpenAPI
1Kosmos · Orchestration

Workflows API

Define and run identity-orchestration workflows, end to end.

Authentication → All products

The Workflow service defines and runs identity-orchestration workflows. Model a flow as nodes, launch instances, and collect per-instance results — the automation layer that strings 1Kosmos services into a journey.

33 endpoints

across 12 resource groups.

ECDSA-signed

every request is signed with your key pair.

JSON over HTTPS

predictable REST, conventional status codes.

OpenAPI 3.0

Download the spec →

Reference

Base URL

All Workflows endpoints are relative to your environment host. Examples on this page use the 1Kosmos pilot environment — swap in your production root when you go live.

Pilot https://pilot-root.1kosmos.net/workflowapi

Content type

Requests and responses use application/json.

GEThttps://pilot-root.1kosmos.net/workflowapi/healthz
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Security

Authentication

Workflows uses ECDSA key-pair authentication. Each request carries your credentials as HTTP headers; verification-grade calls additionally sign the request body. Retrieve the system signing key from /publickeys.

Credentials
keyIdECDSA Public Keyheader
keySecretECDSA Private Keyheader
licenseLicense key from License Microserviceheader
GEThttps://pilot-root.1kosmos.net/workflowapi/healthz
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Reference

Errors

Workflows uses conventional HTTP status codes: 2xx success, 4xx a problem with the request, 5xx a service-side error.

StatusMeaningDescription
200 / 204OKThe request succeeded.
400Bad RequestValidation failed.
401UnauthorizedMissing or invalid credentials.
403ForbiddenAuthenticated, but not permitted.
404Not FoundThe resource does not exist.
500Server ErrorSomething went wrong on our side.
4XXerror response
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error"
}
Workflows

Workflow Instance

Launch and manage workflow runs.

GET/workflow_instance/callback_by_access_code/{accessCode}

Create workflow instance by access code (callback)

Creates and returns a workflow instance using an access code (callback endpoint).

  • Requires ECDSA authentication headers
  • Workflow must have direct_access_enabled set to true
  • Optionally accepts a base64-encoded JSON string in the metadata_b64 query parameter to prefill metadata in the workflow instance
  • Returns instance URL and ID for accessing the workflow
Path parameters
NameTypeDescription
accessCoderequiredstringAccess code for the workflow
Query parameters
NameTypeDescription
metadata_b64stringBase64-encoded JSON metadata object (optional)
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA / Try Authorize 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
GEThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/callback_by_access_code/{accessCode}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/callback_by_access_code/<accessCode>?metadata_b64=<metadata_b64>' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET'
RESPONSE
200
400
401
404
500
Successfully created workflow instance
{
  "data": {
    "instanceUrl": "https://example.com/workflow/wf_instance/wfi-123456",
    "wfInstanceId": "wfi-123456"
  }
}
GET/workflow_instance/create_by_access_code/{accessCode}

Create workflow instance by access code

Creates and returns a workflow instance using an access code.

  • Requires ECDSA authentication headers
  • Workflow must have direct_access_enabled set to true
  • Optionally accepts a base64-encoded JSON string in the metadata_b64 query parameter to prefill metadata in the workflow instance
  • Returns instance URL and ID for accessing the workflow

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string), and "ts" (number)

publickey (required)

Public key

Query Parameters

metadata_b64 (optional)

Base64-encoded JSON object containing workflow metadata (not an array). Example decoded JSON:

{
  "firstName": "John",
  "lastName": "Doe",
  "dob": "1990-01-01"
}

Returns

Returns the created workflow instance URL and ID.

This API throws an error if workflow is not found or direct access is disabled.

Path parameters
NameTypeDescription
accessCoderequiredstringAccess code for the workflow
Query parameters
NameTypeDescription
metadata_b64stringBase64-encoded JSON metadata object (optional)
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
x-ext-idstringECDSA-encrypted extension UUID. When present, the server checks extension activation status and conditionally returns a session token.
GEThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/create_by_access_code/{accessCode}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/create_by_access_code/<accessCode>?metadata_b64=<metadata_b64>' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'x-ext-id: <value>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET'
RESPONSE
200
400
401
403
404
500
Successfully created workflow instance
{
  "data": {
    "instanceUrl": "https://adminconsole.example.com/workflow/wf_instance/wfi-123456",
    "wfInstanceId": "wfi-123456",
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}
GET/workflow_instance/recaptcha_config

Fetch reCAPTCHA configuration

Returns the reCAPTCHA configuration for the current tenant and community.

  • Requires Bearer JWT authentication.
  • Only authorized Community Admins can access this endpoint.
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA containing "appid", "uuid", and "ts" (number)
publickeyrequiredstringPublic Key
authorizationstringBearer JWT token (required if using JWT auth)
GEThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/recaptcha_config
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/recaptcha_config' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
401
403
500
Successfully fetched reCAPTCHA configuration
{
  "data": {
    "recaptcha_url": "xxxxxxx",
    "secret_key_ui": "xxxxxxx"
  },
  "publicKey": "xxxxxxx"
}
GET/workflow_instance/{instanceId}/result_summary

Get workflow instance result summary

Returns the summary of a workflow instance if completed, or progress info if in progress.

  • Only a system, service or service_ext key can be used.
  • Key must be authorized for community.
Path parameters
NameTypeDescription
instanceIdrequiredstringWorkflow Instance ID
GEThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/{instanceId}/result_summary
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/<instanceId>/result_summary' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
401
404
Workflow instance summary or progress info
{
  "data": {
    "wfInstanceId": "string",
    "metaData": {
      "firstName": "string",
      "lastName": "string",
      "dob": "string"
    },
    "workflowId": "string",
    "tenantId": "string",
    "communityId": "string",
    "status": "string",
    "expiresAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "startAt": "string",
    "summary": {
      "person_info": {
        "firstName": "string",
        "lastName": "string",
        "dob": "string"
      },
      "docsScanned": [
        "string"
      ]
    }
  }
}
GET/workflow_instance/{instanceId}/results

Get all workflow instance node results

Returns an array of node results (nodeId, nodeType, resultData) for a given workflow instance.

  • System nodes are excluded from the response.
  • Only a system, service, service_ext or app key can be used.
  • Key must be authorized for community.
Path parameters
NameTypeDescription
instanceIdrequiredstringWorkflow Instance ID
Headers
NameTypeDescription
authorizationstringJWT Access Token / Try Authorize 🔒
GEThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/{instanceId}/results
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/<instanceId>/results' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
401
404
500
List of node results for the workflow instance
{
  "data": [
    {
      "nodeId": "form_1",
      "nodeType": "form",
      "resultData": {
        "email": "kakar_manik@yahoo.com"
      }
    }
  ]
}
GET/workflow_instance/{wfInstanceId}/tenant/{tenantId}/community/{communityId}

Get workflow instance details with node list

Returns workflow instance details including workflow information and paginated list of nodes with their execution status.

  • Requires JWT token with workflow.instance.view or workflow.manage permission OR
  • License with authLevel: system, service, or service_ext
  • Supports pagination for node list
Path parameters
NameTypeDescription
wfInstanceIdrequiredstringWorkflow Instance ID
tenantIdrequiredstringTenant ID
communityIdrequiredstringCommunity ID
Query parameters
NameTypeDescription
pIndexintegerPage index for pagination (optional, default 0, min 0)
pSizeintegerNumber of nodes per page (optional, default 10, min 1, max 100)
Headers
NameTypeDescription
licensekeystringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
authorizationstringJWT Access Token / Try Authorize 🔒
GEThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/{wfInstanceId}/tenant/{tenantId}/community/{communityId}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/wfi-5c79fc5c-8a97-4b8b-ab8c-3e196f266946/tenant/tenant-123/community/community-456?pIndex=0&pSize=10' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
400
401
403
404
500
Successfully fetched workflow instance details
{
  "data": {
    "workflowId": "wf-123456",
    "workflowName": "Identity Verification Workflow",
    "wfInstanceId": "wfi-5c79fc5c-8a97-4b8b-ab8c-3e196f266946",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "expiresAt": "2024-01-16T10:30:00.000Z",
    "list": [
      {
        "nodeId": "form_001",
        "nodeType": "form",
        "status": "COMPLETED",
        "createdAt": "2024-01-15T10:35:00.000Z",
        "updatedAt": "2024-01-15T10:40:00.000Z"
      }
    ],
    "page": {
      "index": 0,
      "size": 10,
      "total": 25
    }
  }
}
POST/workflow_instance/initiate

Initiate workflow instance

Initiate a workflow instance.

Headers

requestid (required)

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

publickey (required)

Public key

Request Body

wfInstanceId (required)

Workflow instance ID to initiate

deviceFingerprint (optional)

Device fingerprint for initiation

Returns

Returns the initiated workflow instance and errors if any.

This API throws an error if something goes wrong.

Headers
NameTypeDescription
requestidrequiredstringJSON 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 &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains below fields to initiate workflow instance.

{
  "wfInstanceId": "xxxxxxxxxxxxx",
  "deviceFingerprint": "abc123"
}
FieldTypeDescription
datarequiredobject—
POSThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/initiate
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/initiate' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"wfInstanceId": "wfi-5c79fc5c-8a97-4b8b-ab8c-3e196f266946", "deviceFingerprint": "32b7615d1f8708e1e25d43640259f"}}'
RESPONSE
200
400
401
403
500
Success
{
  "data": {
    "wfInstanceId": "xxxxxxxxxxxxx",
    "nodes": [
      "abc123"
    ],
    "nextNodeId": "form_002",
    "nextNodeType": "form"
  }
}
POST/workflow_instance/send/notification

Send workflow instance notification (SMS or Email)

Sends a notification (SMS or Email) for a workflow instance to the specified recipient.

  • Requires Bearer JWT authentication.
  • Only authorized users with workflow creation/management permissions can access this endpoint.
  • If type is sms, both smsTo and smsISDCode are required.
  • If type is email, emailTo is required
  • instanceUrl is always required.
  • Either captchaToken or license must be provided (but not both).
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA containing "appid", "uuid", and "ts" (number)
publickeyrequiredstringPublic Key
authorizationstringBearer JWT token (required if using JWT auth)
Request body

Request body for sending notification for a workflow instance. Example (sms):

{
  "data": {
    "type": "sms",
    "smsTo": "XXXXXXXXXX",
    "smsISDCode": "+XX",
    "instanceUrl": "https://domain.com/workflow/wf_instance/xxxxx",
    "license": "xxxxxxxxxxx"
  }
}

Example (email):

{
  "data": {
    "type": "email",
    "emailTo": "example@example.com",
    "instanceUrl": "https://domain.com/workflow/wf_instance/xxxxx",
    "captchaToken": "xxxxxxx"
  }
}
  • If type is sms, smsTo and smsISDCode are required.
  • If type is email, emailTo is required
  • instanceUrl is always required.
  • Either captchaToken or license(system or service level) must be provided (but not both).
FieldTypeDescription
datarequiredobject—
POSThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/send/notification
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/send/notification' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"type": "sms", "smsTo": "XXXXXXXXXX", "smsISDCode": "+91", "emailTo": "example@example.com", "instanceUrl": "https://domain.com/workflow/wf_instance/xxxxx", "captchaToken": "string", "license": "string"}}'
RESPONSE
200
400
401
403
500
Notification sent successfully
{
  "data": {
    "status": "sent",
    "messageId": "msg-7890"
  }
}
POST/workflow_instance/tenant/{tenantId}/community/{communityId}/create

Create workflow instance

Create a workflow instance.

  • Only a system, service or service_ext key can be used to create workflow instance.
  • Key must be authorized for community.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

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

publickey (required)

Public key

Request Body

workflowId (required)

Workflow ID

metaData (optional)

Metadata for the workflow instance

Returns

Returns the created workflow instance and errors if any.

This API throws an error if something goes wrong.

Path parameters
NameTypeDescription
tenantIdrequiredstringTenant ID
communityIdrequiredstringCommunity ID
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON 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 &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
authorizationrequiredstringJWT Access Token / Try Authorize 🔒
Request body

Request body contains below fields to create workflow instance.

{
  "workflowId": "xxxxxxxxxxxxx",
  "metaData": { "firstName": "", "lastName": "", "dob": "" } (optional),
}
FieldTypeDescription
dataobject—
POSThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/tenant/{tenantId}/community/{communityId}/create
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/tenant/tenant-123/community/community-456/create' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"workflowId": "xxxxxxxxxxxx", "metaData": {"firstName": "John", "lastName": "Doe", "dob": "19900101"}}}'
RESPONSE
200
400
401
403
500
Success
{
  "data": {
    "wfInstanceId": "xxxxxxxxxxxx",
    "wfInstanceUrl": "https://example.com/workflow/xxxxxxxxxxxx"
  }
}
POST/workflow_instance/tenant/{tenantId}/community/{communityId}/list

List workflow instances

Returns a paginated list of workflow instances for a given tenant and community.

  • Requires either a valid JWT token with workflow.instance.view or workflow.manage permission or a valid community license.
  • Supported auth levels: system, service, service_ext
  • Pagination parameters pSize and pIndex are required
  • Supports optional filters: status, wfInstanceId

Headers

licensekey or JWT Token (required)

License key encrypted with ECDSA or Bearer JWT token

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds

publickey (required)

Public key

authorization (optional)

JWT Access Token (if using JWT authentication)

Request Body

pSize (required)

Page size (min: 1, max: 100)

pIndex (required)

Page index (0-based)

query (optional)

Object containing optional filter parameters

query.status (optional)

Array of workflow instance statuses to filter by (PENDING, STARTED, EXPIRED, COMPLETED, FAILED, SUCCESS, INPROGRESS, NOT_PERFORMED)

query.wfInstanceId (optional)

Filter by workflow instance ID (supports partial search, case-insensitive)

query.workflowId (optional)

Filter by workflow ID (exact match)

query.from (optional)

Filter instances updated from this ISO 8601 date-time (e.g., 2026-02-10T00:00:00.000Z). Must be within last 90 days from now. Required if 'to' is provided.

query.to (optional)

Filter instances updated until this ISO 8601 date-time (e.g., 2026-02-10T23:59:59.999Z). Must be greater than or equal to 'from'. Required if 'from' is provided.

query.customFilters (optional)

Array of custom filter objects (max 5 filters allowed). Each filter has 'key' and 'value' properties.

Returns

Returns a paginated list of workflow instances with wfInstanceId, workflowId, status, and updatedAt fields.

Also includes page details (total, index, size).

Path parameters
NameTypeDescription
tenantIdrequiredstringTenant ID
communityIdrequiredstringCommunity ID
Headers
NameTypeDescription
licensekeystringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
authorizationstringJWT Access Token / Try Authorize 🔒
Request body

Request body contains pagination and filter parameters.

{
  "data": {
    "pSize": 10,
    "pIndex": 0,
    "query": {
      "status": ["COMPLETED", "STARTED"],
      "wfInstanceId": "wfi-5c79",
      "workflowId": "wf-123456",
      "from": "2026-01-01T00:00:00.000Z",
      "to": "2026-01-31T23:59:59.999Z",
      "customFilters": [
        {
          "key": "firstName",
          "value": "John"
        },
        {
          "key": "lastName",
          "value": "Doe"
        }
      ]
    }
  }
}

pSize and pIndex are required. The query object is optional. wfInstanceId supports partial search (case-insensitive). from and to are ISO 8601 date-time strings (same format as createdAt/updatedAt) for filtering by updatedAt. Both from and to must be provided together. from must be within last 90 days. to must be >= from. customFilters is an array of key-value pairs (max 5 filters allowed).

FieldTypeDescription
datarequiredobject—
POSThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/tenant/{tenantId}/community/{communityId}/list
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/tenant/tenant-123/community/community-456/list' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"pSize": 10, "pIndex": 0, "query": {"status": ["COMPLETED", "STARTED"], "wfInstanceId": "wfi-5c79fc5c", "workflowId": "wf-123456", "from": "2026-01-01T00:00:00.000Z", "to": "2026-01-31T23:59:59.999Z", "customFilters": [{"key": "firstName", "value": "John"}]}}}'
RESPONSE
200
400
401
403
500
Successfully retrieved workflow instances list
{
  "data": {
    "list": [
      {
        "wfInstanceId": "wfi-5c79fc5c-8a97-4b8b-ab8c-3e196f266946",
        "workflowId": "wf-123456",
        "status": "COMPLETED",
        "updatedAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "page": {
      "total": 150,
      "index": 0,
      "size": 10
    }
  }
}
Workflows

Workflow

Define workflows.

GET/tenant/{tenantId}/community/{communityId}/workflow/dvcid/list

List of v2 DVC IDs for workflows

Returns a list of v2 DVC IDs used in workflows for the specified tenant and community.

  • Only a system, service, or service_ext key can access this endpoint.
  • Key must be authorized for the tenant and community.
  • You must provide either a valid licensekey or a JWT access token.
  • All requests must include requestid and publickey headers as described below.
HeaderRequiredDescription
licensekeyYes*License key encrypted with ECDSA
authorizationYes*JWT Access Token (Bearer)
requestidYesJSON string encrypted with ECDSA (appid, uuid, ts)
publickeyYesPublic key

*One of <code>licensekey</code> or <code>authorization</code> is required. If using JWT, provide it in the <code>authorization</code> header.

Path parameters
NameTypeDescription
tenantIdrequiredstringID of the tenant
communityIdrequiredstringID of the community
Query parameters
NameTypeDescription
pSizeintegerPage size for pagination (optional, default 10, min 1, max 100)
pIndexintegerPage index for pagination (optional, default 0)
Headers
NameTypeDescription
licensekeystringLicense key encrypted with ECDSA / Try Authorize 🔒
authorizationstringJWT Access Token (Bearer) / Try Authorize 🔒
requestidrequiredstringJSON string encrypted with ECDSA (appid, uuid, ts) / Try Authorize 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
GEThttps://pilot-root.1kosmos.net/workflowapi/tenant/{tenantId}/community/{communityId}/workflow/dvcid/list
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/tenant/tenantId/community/communityId/workflow/dvcid/list?pSize=10&pIndex=0' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
400
401
403
404
500
Success - List of DVC IDs
{
  "data": {
    "list": [
      {
        "journeyType": "string",
        "name": "string",
        "tag": "string"
      }
    ]
  }
}
GET/tenant/{tenantId}/community/{communityId}/workflow/{workflowId}

Get workflow by ID

Fetch workflow configuration by workflowId for a given tenant and community.

  • Requires ECDSA authenticated headers.
  • Key must be authorized for tenant and community.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number)

publickey (required)

Public key

Path parameters
NameTypeDescription
tenantIdrequiredstringID of the tenant
communityIdrequiredstringID of the community
workflowIdrequiredstringworkflowId of the workflow
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize 🔒
requestidrequiredstringEncrypted JSON string with appid, uuid, and timestamp / Try Authorize 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
authorizationrequiredstringJWT Access Token / Try Authorize 🔒
GEThttps://pilot-root.1kosmos.net/workflowapi/tenant/{tenantId}/community/{communityId}/workflow/{workflowId}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/tenant/tenantId/community/communityId/workflow/workflowId' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
400
401
403
404
500
Workflow configuration
{
  "data": {
    "workflowId": "string",
    "name": "string",
    "version": "string",
    "tenantId": "string",
    "communityId": "string",
    "poiOn": true,
    "isPublished": true,
    "nodes": [
      {}
    ]
  }
}
POST/tenant/{tenantId}/community/{communityId}/workflow/{id}/manage_direct_access

Manage direct access settings for workflow

Enables a direct access code to be created for the workflow. This allows a workflow instance to be created automatically when the access code is invoked. Access code is long lived and does not require to be recreated. Normally, when direct access is not enabled, the endpoint to create workflow instance must be called explicitly to create a new instance.

  • Only a system, service, or service_ext key can manage direct access.
  • Key must be authorized for the tenant and community.
  • Either regenerate or enable must be provided in the request body.
Path parameters
NameTypeDescription
tenantIdrequiredstringID of the tenant
communityIdrequiredstringID of the community
idrequiredstringWorkflow ID
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize 🔒
requestidrequiredstringEncrypted JSON string with appid, uuid, and timestamp / Try Authorize 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
Request body

Request body for managing direct access settings. This API expects the payload under a top-level data object.

FieldTypeDescription
datarequiredobjectDirect access configuration payload
POSThttps://pilot-root.1kosmos.net/workflowapi/tenant/{tenantId}/community/{communityId}/workflow/{id}/manage_direct_access
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/tenant/tenantId/community/communityId/workflow/wf-123/manage_direct_access' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"regenerate": true, "enable": true}}'
RESPONSE
200
400
401
403
404
500
Success
{
  "data": {
    "accessCode": "Ab1_c2",
    "directAccessEnabled": true
  }
}
POST/tenant/{tenantId}/community/{communityId}/workflows

List workflows for a community

Fetch paginated list of workflows for a tenant's community.

  • Only a <b>system</b>, <b>service</b>, or <b>service_ext</b> key can fetch workflows.
  • Key must be authorized for the tenant and community.
  • Results are sorted by <b>updatedAt</b> (last modified) in descending order.
  • Supports pagination via <b>pIndex</b> (page index, 0-based) and <b>pSize</b> (page size, default 10, max 100).
  • The <b>query</b> object can be used to filter workflows by any field (e.g. name, type, etc).
HeaderRequiredDescription
licensekeyYes*License key encrypted with ECDSA
authorizationYes*JWT Access Token (Bearer)
requestidYesJSON string encrypted with ECDSA (appid, uuid, ts)
publickeyYesPublic key

*One of <code>licensekey</code> or <code>authorization</code> is required. If using JWT, provide it in the <code>authorization</code> header.

Path parameters
NameTypeDescription
tenantIdrequiredstringID of the tenant
communityIdrequiredstringID of the community
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize 🔒
requestidrequiredstringEncrypted JSON string with appid, uuid, and timestamp / Try Authorize 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
authorizationrequiredstringJWT Access Token / Try Authorize 🔒
Request body
FieldTypeDescription
dataobject—
POSThttps://pilot-root.1kosmos.net/workflowapi/tenant/{tenantId}/community/{communityId}/workflows
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/tenant/tenantId/community/communityId/workflows' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"query": {}, "pIndex": 0, "pSize": 10}}'
RESPONSE
200
400
401
403
404
500
Paginated workflows list
{
  "data": {
    "data": [
      {
        "workflowId": "wf-123",
        "name": "Sample Workflow",
        "updatedAt": "2026-01-15T12:34:56.789Z",
        "createdAt": "2025-12-01T09:00:00.000Z"
      }
    ],
    "page": {
      "index": 0,
      "size": 10,
      "total": 125
    }
  }
}
PUT/tenant/{tenantId}/community/{communityId}/workflow

Create workflow

Create a workflow configuration.

  • Only a system, service, or service_ext key can be used to create workflow.
  • Key must be authorized for the given tenant and community.

Headers

licensekey or JWT Token (required)

License key encrypted with ECDSA or Bearer JWT token

requestid (required)

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

publickey (required)

Public key

Path parameters
NameTypeDescription
tenantIdrequiredstringID of the tenant
communityIdrequiredstringID of the community
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize 🔒
requestidrequiredstringJSON string encrypted with ECDSA (appid, uuid, ts) / Try Authorize 🔒
authorizationrequiredstringJWT Access Token / Try Authorize 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
Request body

Request body for creating a workflow.

{
  "version": "v1",
  "name": "Sample Workflow",
  "type": "IAL2",
  "dvcId": "device-789",
  "poiOn": true,
  "isPublished": false,
  "styleSheet": "json-string",
  "nodes": [
    { "id": "node-1", "name": "Start Node" },
    { "id": "node-2", "name": "Approval Node" }
  ],
  "canvasData": { },
  "header": { type: 'html', html: '' },
  "footer": { type: 'html', html: '' }
}
FieldTypeDescription
dataobject—
PUThttps://pilot-root.1kosmos.net/workflowapi/tenant/{tenantId}/community/{communityId}/workflow
cURL
Node.js
Python
curl -X PUT 'https://pilot-root.1kosmos.net/workflowapi/tenant/tenantId/community/communityId/workflow' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"version": "v1", "name": "Sample Workflow", "styleSheet": "json-string", "type": "IAL2", "dvcId": "device-789", "poiOn": true, "isPublished": false, "nodes": [{"id": "node-1", "name": "Start Node"}], "canvasData": {}, "header": {"type": "html", "html": ""}, "footer": {"type": "html", "html": ""}}}'
RESPONSE
200
400
401
403
500
Success
{
  "data": {
    "workflowId": "xxxxxxxxxxxxx"
  }
}
PATCH/tenant/{tenantId}/community/{communityId}/workflow/{id}

Update workflow configuration

Update an existing workflow configuration.

  • Only a system, service, or service_ext key can update workflow.
  • Key must be authorized for the given tenant and community.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

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

publickey (required)

Public key

Path parameters
NameTypeDescription
tenantIdrequiredstringID of the tenant
communityIdrequiredstringID of the community
idrequiredstringWorkflow ID
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize 🔒
requestidrequiredstringJSON string encrypted with ECDSA (appid, uuid, ts) / Try Authorize 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
authorizationrequiredstringJWT Access Token / Try Authorize 🔒
Request body

Request body for updating a workflow. The payload must be an object with a top-level data object containing the workflow configuration.

FieldTypeDescription
datarequiredobjectWorkflow configuration payload
PATCHhttps://pilot-root.1kosmos.net/workflowapi/tenant/{tenantId}/community/{communityId}/workflow/{id}
cURL
Node.js
Python
curl -X PATCH 'https://pilot-root.1kosmos.net/workflowapi/tenant/tenantId/community/communityId/workflow/wf-123' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"version": "v1", "name": "Sample Workflow", "type": "IAL2", "dvcId": "device-789", "poiOn": true, "isPublished": false, "styleSheet": "{}", "nodes": [{"id": "node-1", "name": "Start Node"}], "canvasData": {}, "header": {"type": "html", "html": ""}, "footer": {"type": "html", "html": ""}}}'
RESPONSE
200
400
401
403
404
500
Success
{
  "data": {}
}
DELETE/tenant/{tenantId}/community/{communityId}/workflow/{workflowId}

Delete workflow by ID

Delete a workflow configuration.

  • Only a system, service, or service_ext key can delete a workflow.
  • Key must be authorized for the tenant and community.
Path parameters
NameTypeDescription
tenantIdrequiredstringTenant ID
communityIdrequiredstringCommunity ID
workflowIdrequiredstringWorkflow ID
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize 🔒
requestidrequiredstringEncrypted JSON string with appid, uuid and ts / Try Authorize 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
authorizationrequiredstringJWT Access Token / Try Authorize 🔒
DELETEhttps://pilot-root.1kosmos.net/workflowapi/tenant/{tenantId}/community/{communityId}/workflow/{workflowId}
cURL
Node.js
Python
curl -X DELETE 'https://pilot-root.1kosmos.net/workflowapi/tenant/<tenantId>/community/<communityId>/workflow/<workflowId>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
204
400
401
403
404
500
No Content - workflow successfully deleted
// no response body
Workflows

Workflow Instance Result

Fetch workflow results.

GET/workflow_instance/{wfInstanceId}/tenant/{tenantId}/community/{communityId}/execute_node/{nodeId}

Execute a single orphan node

Executes a single orphan JavaScript node directly from the UI without full workflow traversal.

Authentication: None required (no ECDSA, no API key).

Behavior:

  • Executes only the specified nodeId
  • Node must be an orphan node (no active handlers / connections such as on_success, on_fail, on_error, on_next, on_check_resolution_fail)
  • No entry/exit traversal is performed

Validations:

  • nodeId must be present and found in the workflow
  • tenantId / communityId must be valid and mapped to the given wfInstanceId
  • Node must be an orphan (no active handlers enabled or connected)
Path parameters
NameTypeDescription
wfInstanceIdrequiredstringWorkflow Instance ID
tenantIdrequiredstringTenant ID
communityIdrequiredstringCommunity ID
nodeIdrequiredstringID of the orphan node to execute
GEThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/{wfInstanceId}/tenant/{tenantId}/community/{communityId}/execute_node/{nodeId}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/<wfInstanceId>/tenant/<tenantId>/community/<communityId>/execute_node/<nodeId>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
400
404
500
Node executed. Check the `success` field to distinguish outcomes: - `success: true` — node executed and returned a result. - `success: false` — node executed but returned no result (treated as failed).
{
  "success": true,
  "nodeId": "js_node_001",
  "result": {},
  "error": "Node execution returned no result"
}
GET/workflow_instance/{wfInstanceId}/tenant/{tenantId}/community/{communityId}/node/{nodeId}

Get workflow instance result by node

Fetches the workflow instance result for a specific node.

  • Requires either a valid JWT with workflow.create, workflow.manage or workflow.instance.view permission, or system/service/service_ext license
  • Returns whatever data is present in the database for the specified node
  • System nodes (nodeType: 'system') are not allowed to be exposed and will return a 403 Forbidden error
Path parameters
NameTypeDescription
wfInstanceIdrequiredstringWorkflow Instance ID
tenantIdrequiredstringTenant ID
communityIdrequiredstringCommunity ID
nodeIdrequiredstringNode ID
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
authorizationstringBearer JWT token (optional if using license) / Try Authorize 🔒
licensekeystringLicense key encrypted with ECDSA (optional if using JWT) / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/{wfInstanceId}/tenant/{tenantId}/community/{communityId}/node/{nodeId}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/<wfInstanceId>/tenant/<tenantId>/community/<communityId>/node/<nodeId>' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
401
403
404
500
Successfully fetched workflow instance result
{
  "data": {
    "wfInstanceId": "string",
    "nodeId": "string",
    "nodeType": "string",
    "workflowId": "string",
    "tenantId": "string",
    "communityId": "string",
    "status": "string",
    "resultData": {},
    "createdAt": "string",
    "updatedAt": "string"
  }
}
POST/workflow_instance/poll

Poll workflow instance result

Poll the result of a specific node from a workflow instance.

Headers

requestid (required)

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

publickey (required)

Public key

Request Body

wfInstanceId (required)

Workflow Instance ID for which result is being fetched

nodeId (required)

Node ID whose result is being fetched

data (optional)

Additional input data (e.g. device info or empty object)

Returns

Returns the workflow node result if available.

This API throws an error if something goes wrong or if the node result is not yet available.

Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body to fetch workflow instance result.

{
  "data": {
    "wfInstanceId": "5c79fc5c-8a97-4b8b-ab8c-3e196f266946",
    "nodeId": "form_001"
  }
}
FieldTypeDescription
datarequiredobject—
POSThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/poll
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/poll' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"wfInstanceId": "wfi-5c79fc5c-8a97-4b8b-ab8c-3e196f266946", "nodeId": "form_001"}}'
RESPONSE
200
202
400
401
403
404
500
Success - Node result is available
{
  "data": {
    "wfInstanceId": "5c79fc5c-8a97-4b8b-ab8c-3e196f266946",
    "nextNodeId": "form_001",
    "nextNodeType": "form",
    "summary": [
      "Biometric",
      "Passport",
      "Driver's license"
    ]
  }
}
POST/workflow_instance/poll_liveid

Poll liveid workflow instance result

Poll the result of a liveid_capture node from a workflow instance.

Headers

requestid (required)

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

publickey (required)

Public key

Request Body

wfInstanceId (required)

Workflow Instance ID for which result is being fetched

nodeId (required)

Node ID whose result is being fetched

Returns

Returns the workflow node result if available.

This API throws an error if something goes wrong or if the node result is not yet available.

Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body to fetch workflow instance result.

{
  "data": {
    "wfInstanceId": "5c79fc5c-8a97-4b8b-ab8c-3e196f266946",
    "nodeId": "form_001"
  }
}
FieldTypeDescription
datarequiredobject—
POSThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/poll_liveid
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/poll_liveid' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"wfInstanceId": "wfi-5c79fc5c-8a97-4b8b-ab8c-3e196f266946", "nodeId": "form_001"}}'
RESPONSE
200
202
400
401
403
404
500
Success - Node result is available
{
  "data": {
    "wfInstanceId": "5c79fc5c-8a97-4b8b-ab8c-3e196f266946",
    "nextNodeId": "form_001",
    "nextNodeType": "form",
    "summary": [
      "Biometric",
      "Passport",
      "Driver's license"
    ]
  }
}
POST/workflow_instance/submit_result

Create workflow instance result

Create a workflow instance result.

Headers

requestid (required)

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

publickey (required)

Public key

Request Body

wfInstanceId (required)

Workflow instance ID

nodeId (required)

Node ID for which result is being created

result (optional)

Result data

Returns

Returns the created workflow instance result and errors if any.

This API throws an error if something goes wrong.

Headers
NameTypeDescription
requestidrequiredstringJSON 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 &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains below fields to create workflow instance result.

{
  "wfInstanceId": "xxxxxxxxxxxxx",
  "nodeId": "node-1",
  "nodeType": "form",
  "requestData": { "field1": "value1", "selfie": "base64EncodedImage" }
}
FieldTypeDescription
dataobject—
POSThttps://pilot-root.1kosmos.net/workflowapi/workflow_instance/submit_result
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/workflow_instance/submit_result' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"wfInstanceId": "xxxxxxxxxxxxx", "nodeId": "node-1", "nodeType": "form", "requestData": {"field1": "value1", "field2": "value2"}}}'
RESPONSE
200
400
401
403
500
Success
{
  "data": {
    "wfInstanceId": "5c79fc5c-8a97-4b8b-ab8c-3e196f266946",
    "nextNodeId": "form_001",
    "nextNodeType": "form",
    "summary": [
      "Biometric",
      "Passport",
      "Driver's license"
    ]
  }
}
Workflows

Service Key

Service Key endpoints.

GET/servicekeys

Get service keys

This endpoint returns available service keys. The license you are using must be of authLevel 'system'

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

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

publickey (required)

Public key

Returns

Returns array with service keys

Headers
NameTypeDescription
requestidrequiredstringJSON 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 &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/workflowapi/servicekeys
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/servicekeys' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
400
401
403
500
Success
[
  {
    "tag": "xxxxx",
    "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "type": "xxxxx"
  }
]
DELETE/servicekey/{keyId}

Reset Service Key

This endpoint resets service key for given keyId. Deletes current one and recreates a new one. The license you are using must be of authLevel 'system'

Parameters

keyId (required)

The keyId of service key to reset

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

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

publickey (required)

Public key

Returns

Returns re-created service key

Path parameters
NameTypeDescription
keyIdrequiredstringkeyId of service key to reset
Headers
NameTypeDescription
requestidrequiredstringJSON 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 &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
DELETEhttps://pilot-root.1kosmos.net/workflowapi/servicekey/{keyId}
cURL
Node.js
Python
curl -X DELETE 'https://pilot-root.1kosmos.net/workflowapi/servicekey/<keyId>' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
400
401
500
Success
[
  {
    "tag": "xxxxx",
    "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "type": "xxxxx"
  }
]
Workflows

ECDSA Helper

ECDSA Helper endpoints.

POST/ecdsa_helper/{method}

Encrypt and decrypt the data string by public key and private key.

Encrypt and decrypt the data string by public key and private key.

Parameters

method (optional)

The method parameter is type of enum. Default value is encrypt.

This parameter only accepts following values

encrypt, decrypt

Request Body

dataStr (required)

The dataStr key is type of string.

publicKey (required)

The publicKey is type of string.

privateKey (required)

The privateKey is type of string.

Returns

Returns the encrypted/decrypted string.

This API throw an error if something goes wrong. A common source of error is public or private key is not valid.

Path parameters
NameTypeDescription
methodstring—
Request body
FieldTypeDescription
dataStrstring—
publicKeystring—
privateKeystring—
POSThttps://pilot-root.1kosmos.net/workflowapi/ecdsa_helper/{method}
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/ecdsa_helper/<method>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"dataStr": "Hey, This is example data string.", "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=", "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="}'
RESPONSE
200
successful operation
{
  "data": "xxxxxxxxxxxxxxxxxxxx",
  "publicKey": "xxxxxxxxxxxxxxxxxxxx"
}
Workflows

Environment

Environment endpoints.

GET/environment

/environment

Provide details regarding the environments.

Returns

Returns an environment object

GEThttps://pilot-root.1kosmos.net/workflowapi/environment
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/environment' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
Success
// no response body
Workflows

Healthz

Healthz endpoints.

GET/healthz

Get healthz.

Get healthz

Returns

Returns a healthz object

  • ``version = <git-tag>.<commit-id>.<dob>``
  • ``git-tag``: When code is compiled from a git-tag, this must carry the tag name. This should match one of the git tags.
  • ``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.
  • ``dob``: Date Of Build. This is epoc-time-in-se conds that tell the time when the build was created.
  • ​if the code is not built from a git-tag, then the ``version =<commit-id>.<dob>``
GEThttps://pilot-root.1kosmos.net/workflowapi/healthz
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
Success ``` { "status": "all services operational", "publicKey": "string" //same as <service>/publickeys endpoint, "code": "200", "version": "<version>" //as defined above } ```
{
  "status": "all services operational",
  "publicKey": "//same as <service>/publickeys endpoint",
  "code": "200",
  "version": "xxxx.xxxx.xxxx"
}
Workflows

JWT

JWT endpoints.

POST/jwt/verifyToken

Verify JWT token

Verifies a JWT token and checks if the user has an active login session. If the user does not exist, is disabled, or inactive, all login sessions are destroyed.

Headers
NameTypeDescription
requestidrequiredstringJSON 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 &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
authorizationrequiredstringBearer JWT token.
Request body

Encrypted request body containing the JWT token. For Swagger preview, unencrypted data is accepted.

FieldTypeDescription
dataobject—
POSThttps://pilot-root.1kosmos.net/workflowapi/jwt/verifyToken
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/workflowapi/jwt/verifyToken' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"token": "string"}}'
RESPONSE
200
401
Decoded token value.
{
  "data": "object",
  "publicKey": "string"
}
Workflows

Public Key

Public Key endpoints.

GET/publickeys

Get system's public key.

Get system's public key.

Returns

Returns a public key object

GEThttps://pilot-root.1kosmos.net/workflowapi/publickeys
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/publickeys' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
401
{
  "publicKey": ""
}
Workflows

Service Directory

Service Directory endpoints.

GET/sd

Get all service directories.

Get all service directories.

Returns

Returns all service directories.

GEThttps://pilot-root.1kosmos.net/workflowapi/sd
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/sd' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
{
  "name1": "https://xxx.xxxxxx.xxx/xxxxx",
  "name2": "https://xxx.xxxxxx.xxx/xxxxx",
  "name3": "https://xxx.xxxxxx.xxx/xxxxx"
}
Workflows

Well Known config

Well Known config endpoints.

GET/.well-known

Get well known config.

Get well known config

Returns

Returns an object

GEThttps://pilot-root.1kosmos.net/workflowapi/.well-known
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/.well-known' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
Success ``` { "public_key": "string" //same as <service>/publickeys endpoint, } ```
{
  "public_key": "//same as <service>/publickeys endpoint"
}
Workflows

Workflow Node

Workflow node catalog.

GET/v0/tenant/{tenantId}/community/{communityId}/workflow/node/library

Get workflow node library

Returns the list of workflow node categories, elements, handler keys, and default header & footer templates.

<b>Authentication & Headers:</b>

  • Requires ECDSA authenticated headers and appropriate permissions.
  • You must provide <b>either</b> a valid <b>licensekey</b> <b>or</b> a <b>JWT access token</b>.
  • All requests must include <b>requestid</b> and <b>publickey</b> headers as described below.
HeaderRequiredDescription
licensekeyYes*License key encrypted with ECDSA
authorizationYes*JWT Access Token (Bearer), e.g. Bearer <token>
requestidYesJSON string encrypted with ECDSA (appid, uuid, ts)
publickeyYesPublic key

*One of <code>licensekey</code> or <code>authorization</code> is required. If using JWT, provide it in the <code>authorization</code> header.

<b>Permissions:</b> SYSTEM, SERVICE, or SERVICE_EXT required.

<b>Response fields:</b> All fields below are always returned.

Path parameters
NameTypeDescription
tenantIdrequiredstringID of the tenant
communityIdrequiredstringID of the community
Headers
NameTypeDescription
licensekeystringLicense key encrypted with ECDSA / Try Authorize 🔒
authorizationstringJWT Access Token (Bearer) / Try Authorize 🔒
requestidrequiredstringJSON string encrypted with ECDSA (appid, uuid, ts) / Try Authorize 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
GEThttps://pilot-root.1kosmos.net/workflowapi/v0/tenant/{tenantId}/community/{communityId}/workflow/node/library
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/workflowapi/v0/tenant/tenantId/community/communityId/workflow/node/library' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'
RESPONSE
200
401
403
500
Success
{
  "data": {
    "categories": [
      {
        "id": "category-1",
        "title": "Document Verification Nodes",
        "styles": {
          "bg_color": "#123456",
          "logo-image": "xxxxxxxxx"
        },
        "elements": [
          "element-1"
        ]
      }
    ],
    "elements": [
      {
        "id": "element-1",
        "name": "Form Node",
        "styles": {
          "bg_color": "#123456",
          "logo-image": "xxxxxxxxx"
        },
        "node": {
          "type": "form",
          "fields": []
        },
        "description": "Performs verification on uploaded documents."
      }
    ],
    "handlerKeys": [
      {
        "key": "string",
        "label": "string"
      }
    ],
    "templates": {
      "header": "string",
      "footer": "string"
    }
  }
}
© 2026 1Kosmos · Workflow service v1.00.09Generated from the OpenAPI spec · workflowapi.json