Config & Consentv2.1pilot-root.1kosmos.net/caasOpenAPI
1Kosmos · Configuration & Consent

Config & Consent API

Centralized tenant configuration, secrets and consent management.

Authentication → All products

The Configuration & Consent service centralizes tenant configuration, secrets and consent records. Manage environment configuration, a secure secret store, platform extensions and user consent from one place.

20 endpoints

across 9 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 Config & Consent 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/caas

Content type

Requests and responses use application/json.

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

Authentication

Config & Consent 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 APIheader
GEThttps://pilot-root.1kosmos.net/caas/healthz
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/caas/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
Reference

Errors

Config & Consent 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"
}
Config & Consent

Configuration

Tenant configuration.

POST/config/fetch

Fetch configuration

Fetch configuration for provided context and key paths or full configuration.

  • If context is {tenantId, communityId} license key must be authorized for community, active and not expired.
  • If context is {personId, mobile_app_id} license key must be active (disable = false) and not expired.
  • If context is {appId} license key must be active (disable = false) and not expired.
  • In addition {if appId is either 'adminconsole.global' or 'platform'} license key must be active and authLevel must be [system | service | service_ext | app | app_ext]
  • Additionally add boolean 'internal' to context to limit reads by system/service alone

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

context (required)

The context is a type of object. It will be used to generate a unique key to find configuration record.

key_paths (optional)

The key_paths of values to fetch.

  • To get full configuration do not specify key_path attribute in request body.

Returns

Returns the key path and values of stored configuration.

This API throws an error if something goes wrong.

Query parameters
NameTypeDescription
read_freshbooleanread_fresh is used to read fresh data.
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize 🔒
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 🔒
publickeyrequiredstringPublic Key / Try Authorize 🔒
Request body
FieldTypeDescription
contextobjectContext object.
key_pathsarray<object>Key path array.
POSThttps://pilot-root.1kosmos.net/caas/config/fetch
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/caas/config/fetch?read_fresh=True' \
  -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 '{"context": {}, "key_paths": ["xxx", "xxx.xxx", "xxx.xxx.xxx"]}'
RESPONSE
200
400
401
Returns matched key path with values.
// no response body
PUT/config/{key_path}

Set configuration

Set configuration for provided context.

  • If context is {tenantId, communityId} license key must authorized for community, active and not expired and authLevel must be [system, service, service_ext].
  • If context is {personId, mobile_app_id} license key must be active (disable = false) and not expired and authLevel must be [system, service, service_ext, app, app_ext].
  • If context is {appId} license key must be active (disable = false) and not expired, and authLevel must be [system, service, service_ext].
  • In addition {if appId is either 'adminconsole.global' or 'platform'} license key must be active, and authLevel must be [system, service].
  • Additionally add boolean 'internal' to context to limit writes/remove by system/service alone

Parameters

key_path (required)

The key_path to replace with a new value.

  • Only alphabets, full stop (.) and underscore (_) is allowed in key_path parameter.
  • To replace full configuration submit "data" as the value of key_path parameter.

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

context (required)

The context is a type of object. It will be used to generate a unique key for configuration and will be stored with configuration.

data (required)

The data of the configuration object. Data can be string, number, boolean, array, object.

Returns

Returns the key path of stored configuration.

This API throws an error if something goes wrong.

Path parameters
NameTypeDescription
key_pathstring—
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;
Request body
FieldTypeDescription
contextobjectContext object
dataobjectData object
PUThttps://pilot-root.1kosmos.net/caas/config/{key_path}
cURL
Node.js
Python
curl -X PUT 'https://pilot-root.1kosmos.net/caas/config/xxx.xxxx.xxx' \
  -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 '{"context": {}, "data": {}}'
RESPONSE
200
400
401
Stored key path with values.
// no response body
DELETE/config

Remove configuration

Remove configuration by provided context.

  • If context is {tenantId, communityId} license key must authorized for community, active and not expired and authLevel must be [system, service, service_ext].
  • If context is {personId, mobile_app_id} license key must be active (disable = false) and not expired and authLevel must be [system, service, service_ext, app, app_ext].
  • If context is {appId} license key must be active (disable = false) and not expired and authLevel must be [system, service].
  • In addition {if appId is either 'adminconsole.global' or 'platform'} license key must be active, and authLevel must be [system, service].
  • Additionally add boolean 'internal' to context to limit writes/remove by system alone

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

context (required)

The context is type of object. It will be used to generate unique key for remove configuration.

key_paths (required)

The key_paths is type of array.

Each value of array is used to remove key from configuration object.

Returns

Returns a 204 status code if a valid context and key_paths are provided. This API throws an error if something goes wrong.

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;
Request body
FieldTypeDescription
contextobjectContext object
key_pathsarray<object>Data array
DELETEhttps://pilot-root.1kosmos.net/caas/config
cURL
Node.js
Python
curl -X DELETE 'https://pilot-root.1kosmos.net/caas/config' \
  -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 '{"context": {}, "key_paths": ["xxx.xxx.xx", "xxx"]}'
RESPONSE
204
401
404
No Content
// no response body
GET/tenants/{tenantId}/community/{communityId}/consents/ipfs/{ipfsHash}

Retrieve historical consent by IPFS hash

Retrieve any historical consent document directly from IPFS by its content hash. Response is ECDSA encrypted. When using swagger (requestfromswagger header), response is returned as plain JSON. This endpoint fetches the document content from IPFS without DB lookup.

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

publickey (required)

Public key

Path parameters
NameTypeDescription
tenantIdrequiredstringTenant identifier
communityIdrequiredstringCommunity identifier
ipfsHashrequiredstringIPFS content hash of the consent document
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 / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/caas/tenants/{tenantId}/community/{communityId}/consents/ipfs/{ipfsHash}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/caas/tenants/<tenantId>/community/<communityId>/consents/ipfs/QmAbCdEf123456' \
  -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'
RESPONSE
200
401
404
500
Historical consent document retrieved successfully
{
  "data": {
    "type": "biometric",
    "title": "Biometric Information Consent Form",
    "subtitle": "Please read carefully",
    "body": "string",
    "acknowledgeText": "I agree to the terms",
    "updatedAt": 1750012345,
    "updatedBy": "admin@example.com",
    "docUpdatedAt": 1750012345,
    "consentId": "QmAbCdEf123456",
    "prevConsentId": "QmPrEvIoUs789",
    "isEnabled": true,
    "version": "v1750012345000"
  },
  "publicKey": "string"
}
GET/tenants/{tenantId}/community/{communityId}/consents/{type}

Retrieve consent by type

Retrieve the current consent document for a given type, community, and tenant. Response is ECDSA encrypted. When using swagger (requestfromswagger header), response is returned as plain JSON. If a consent record exists with IPFS content, the content is fetched from IPFS and the signature hash is verified. If no record exists or the record has no IPFS content, a default response is returned with isEnabled set to false and default content fields from the configured template for the given type.

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

publickey (required)

Public key

Path parameters
NameTypeDescription
tenantIdrequiredstringTenant identifier
communityIdrequiredstringCommunity identifier
typerequiredstringConsent type (e.g. biometric)
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 / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/caas/tenants/{tenantId}/community/{communityId}/consents/{type}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/caas/tenants/<tenantId>/community/<communityId>/consents/biometric' \
  -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'
RESPONSE
200
401
500
Consent document retrieved successfully
{
  "data": {
    "type": "biometric",
    "title": "Biometric Information Consent Form",
    "subtitle": "Please read carefully",
    "body": "string",
    "acknowledgeText": "I agree to the terms",
    "updatedAt": 1750012345,
    "updatedBy": "admin@example.com",
    "docUpdatedAt": 1750012345,
    "consentId": "QmAbCdEf123456",
    "prevConsentId": "QmPrEvIoUs789",
    "isEnabled": true,
    "version": "v1750012345000"
  },
  "publicKey": "string"
}
PUT/tenants/{tenantId}/community/{communityId}/consents

Create or update consent

Create or update a consent document for a given community and tenant. Request body must be ECDSA encrypted. When using swagger (requestfromswagger header), plain JSON is accepted. Response is ECDSA encrypted. When using swagger, response is returned as plain JSON. When isEnabled is true and content has changed, the content is written to IPFS with a SHA-512 signature hash and chain linking. When isEnabled is false, only the enabled flag and audit fields are updated — no IPFS write occurs and existing hashes are preserved. When isEnabled is true but content is unchanged, only the enabled flag and audit fields are updated.

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

publickey (required)

Public key

Path parameters
NameTypeDescription
tenantIdrequiredstringTenant identifier
communityIdrequiredstringCommunity identifier
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 / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body
FieldTypeDescription
datarequiredobjectECDSA encrypted consent data (or plain object when using swagger)
PUThttps://pilot-root.1kosmos.net/caas/tenants/{tenantId}/community/{communityId}/consents
cURL
Node.js
Python
curl -X PUT 'https://pilot-root.1kosmos.net/caas/tenants/<tenantId>/community/<communityId>/consents' \
  -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": {"type": "biometric", "isEnabled": true, "title": "Biometric Data Processing Agreement", "body": "PGgzPkJpb21ldHJpYyBDb25zZW50PC9oMz48cD5Db250ZW50Li4uPC9wPg==", "subtitle": "Please read carefully", "acknowledgeText": "I agree to the terms", "requestingUser": "admin@example.com", "eventData": {"user_id": "admin@example.com", "user_name": "admin@example.com", "client_ip_address": "192.168.1.1", "caller_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"}}}'
RESPONSE
200
400
401
500
Consent document created or updated successfully
{
  "data": {
    "type": "biometric",
    "title": "Biometric Information Consent Form",
    "subtitle": "Please read carefully",
    "body": "string",
    "acknowledgeText": "I agree to the terms",
    "updatedAt": 1750012345,
    "updatedBy": "admin@example.com",
    "docUpdatedAt": 1750012345,
    "consentId": "QmAbCdEf123456",
    "prevConsentId": "QmPrEvIoUs789",
    "isEnabled": true,
    "version": "v1750012345000"
  },
  "publicKey": "string"
}
Config & Consent

Environment

Environment endpoints.

GET/environment

/environment

Provide details regarding the environments.

Returns

Returns an environment object

GEThttps://pilot-root.1kosmos.net/caas/environment
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/caas/environment' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
Success
// no response body
POST/environment/create/community

<tbd>.

<tbd>Create Community.

  • Key must be active with authLevel system/service from current license server.. (see /sd)

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

JSON (required)

The JSON object to install a new community

Returns

tbd.

This API throws an error if something goes wrong.

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;
Request body
FieldTypeDescription
communityNamestring—
contactFnamestring—
contactLnamestring—
contactEmailstring—
contactPhonestring—
communityPasswordstring—
smsGatewayobject—
emailGatewayobject—
pushConfigobjectPush notification configuration
POSThttps://pilot-root.1kosmos.net/caas/environment/create/community
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/caas/environment/create/community' \
  -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 '{"communityName": "string", "contactFname": "fname", "contactLname": "lname", "contactEmail": "some@email.com", "contactPhone": "19990009988", "communityPassword": "******", "smsGateway": {"type": "twilio", "username": "username", "password": "*****", "senderPhone": "1111111111", "channels": ["sms", "voice"]}, "emailGateway": {"type": "smtp", "username": "username", "password": "*****", "serviceUrl": "smtp.socketlabs.com", "senderEmail": "no-reply@1kosmos.com", "port": "465", "protocol": "smtp"}, "pushConfig": {"firebase": {"uri": "https://firebase.example.com", "serviceaccount": "/path/to/serviceAccountKey.json", "fcmkey": "AAAA...your_fcm_key"}, "apple": {"host": "api.push.apple.com", "pkcs8file": "/path/to/key.p8", "teamid": "TEAMID123", "keyid": "KEYID456", "appname": "com.example.app"}, "pushy": {"appSecret": "your_pushy_app_secret", "url": "https://api.pushy.me"}}}'
RESPONSE
200
400
401
tbd.
// no response body
POST/environment/install

<tbd>.

<tbd>Install environment.

  • Key must be active with authLevel system from current license server.. (see /sd)

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

JSON (required)

The JSON object to install an environment

Returns

tbd.

This API throws an error if something goes wrong.

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;
Request body
FieldTypeDescription
instanceTypestring—
rootUrlstring—
rootLicencestring—
tenantNamestring—
tenantDNSstring—
tenantTagstring—
contactFnamestring—
contactLnamestring—
contactEmailstring—
contactPhonestring—
tenantPasswordstring—
public_assets_download_urlstring—
smsGatewayobject—
emailGatewayobject—
pushConfigobjectPush notification configuration
recaptchaConfigobjectGoogle reCAPTCHA configuration
analyticsobject—
agentApiobjectAgent API configuration with agent_id as key
POSThttps://pilot-root.1kosmos.net/caas/environment/install
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/caas/environment/install' \
  -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 '{"instanceType": "client-instance", "rootUrl": "https://1k-prod-us.1kosmos.net", "rootLicense": "system|service license from root", "tenantName": "1Kosmos", "tenantDNS": "tenant.1kosmos.net", "tenantTag": "tenanttag", "contactFname": "fname", "contactLname": "lname", "contactEmail": "some@email.com", "contactPhone": "19990009988", "tenantPassword": "******", "public_assets_download_url": "http://ipfs-cluster.static-prod:9095", "smsGateway": {"type": "twilio", "username": "username", "password": "*****", "senderPhone": "1111111111", "channels": ["sms", "voice"]}, "emailGateway": {"type": "smtp", "username": "username", "password": "*****", "serviceUrl": "smtp.socketlabs.com", "senderEmail": "no-reply@1kosmos.com", "port": "465", "protocol": "smtp"}, "pushConfig": {"firebase": {"uri": "https://firebase.example.com", "serviceaccount": "/path/to/serviceAccountKey.json", "fcmkey": "AAAA...your_fcm_key"}, "apple": {"host": "api.push.apple.com", "pkcs8file": "/path/to/key.p8", "teamid": "TEAMID123", "keyid": "KEYID456", "appname": "com.example.app"}, "pushy": {"appSecret": "your_pushy_app_secret", "url": "https://api.pushy.me"}}, "behaviorAuth": {"provider": "behavior-provider", "url": "https://behavior.example.com", "api_key": "your_behavior_api_key", "api_secret": "your_behavior_api_secret", "auth_type": "score"}, "recaptchaConfig": {"secret_key_api": "", "secret_key_ui": "", "recaptcha_api": "https://www.google.com/recaptcha/api/siteverify", "recaptcha_url": "https://www.google.com/recaptcha/api.js"}, "analytics": {"elastic": {"url": "https://search-dev-elastic-kk72cvjrv24lxnsneluxl3l6o4.us-west-1.es.amazonaws.com", "uid": "username", "pwd": "password"}}, "agentApi": {"e258cb75-4f8e-47b1-9e18-e949a2f442b0": {"name": "", "type": "", "url": "", "authType": "api_key", "credential": {"x-api-key": ""}}}}'
RESPONSE
200
400
401
tbd.
// no response body
Config & Consent

Extension

Platform extensions.

POST/extension/activate

Activate a browser extension instance

Activates a browser extension install by binding its UUID to a verified user identity. Request body is ECDSA encrypted. Response is ECDSA encrypted.

Accepts either:

  • OAuth Bearer token with extension:activate scope (from OIDC PKCE flow)
  • License key (system/service/service_ext level)

When using OAuth, the sub claim from token introspection is recorded as activatedBy. When using license key, the key ID is recorded as activatedBy.

Headers

Authorization (option 1)

Bearer token with extension:activate scope

licensekey (option 2)

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

publickey (required)

Public key

Headers
NameTypeDescription
licensekeystringLicense key encrypted with ECDSA (alternative to Bearer token) / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body
FieldTypeDescription
datarequiredobjectECDSA encrypted activation data (or plain object when using swagger)
POSThttps://pilot-root.1kosmos.net/caas/extension/activate
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/caas/extension/activate' \
  -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 'Content-Type: application/json' \
  -d '{"data": {"extensionId": "550e8400-e29b-41d4-a716-446655440000", "tenantDns": "customer.1kosmos.net", "communityName": "default", "metadata": {"browser": "Chrome", "extensionVersion": "1.0.0"}}}'
RESPONSE
200
400
401
500
Extension activated successfully
{
  "data": {
    "status": "active",
    "extensionId": "550e8400-e29b-41d4-a716-446655440000",
    "activatedAt": "2026-05-13T10:30:45.000Z"
  },
  "publicKey": "string"
}
POST/extension/deactivate

Deactivate a browser extension instance

Deactivates a previously activated extension. Admin-only operation. After deactivation, the extension will no longer receive session tokens from the workflow API. Requires license key (system/service/service_ext). Request body is ECDSA encrypted. Response is ECDSA encrypted.

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

publickey (required)

Public key

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 / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body
FieldTypeDescription
datarequiredobjectECDSA encrypted request data (or plain object when using swagger)
POSThttps://pilot-root.1kosmos.net/caas/extension/deactivate
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/caas/extension/deactivate' \
  -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": {"extensionId": "550e8400-e29b-41d4-a716-446655440000", "tenantDns": "customer.1kosmos.net", "communityName": "default", "deactivatedBy": "admin@company.com"}}'
RESPONSE
200
400
401
404
500
Extension deactivated successfully
{
  "data": {
    "extensionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "deactivated",
    "deactivatedAt": "2026-05-14T08:15:30.000Z"
  },
  "publicKey": "string"
}
POST/extension/status

Get extension activation status

Returns the activation status for a given extension ID. Server-to-server only — requires license key (system/service/service_ext). Request body is ECDSA encrypted. Response is ECDSA encrypted.

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

publickey (required)

Public key

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 / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body
FieldTypeDescription
datarequiredobjectECDSA encrypted request data (or plain object when using swagger)
POSThttps://pilot-root.1kosmos.net/caas/extension/status
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/caas/extension/status' \
  -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": {"extensionId": "550e8400-e29b-41d4-a716-446655440000", "tenantDns": "customer.1kosmos.net", "communityName": "default"}}'
RESPONSE
200
400
401
500
Extension status retrieved successfully
{
  "data": {
    "extensionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active",
    "activatedAt": "2026-05-13T10:30:45.000Z",
    "deactivatedAt": null
  },
  "publicKey": "string"
}
Config & Consent

Secret Store

Securely store and retrieve secrets.

POST/tenants/{tenantId}/community/{communityId}/secrets/fetch

Fetch secrets with optional tag filter

Fetch secrets for a specific tenant and community with optional tag filtering.

  • Key must be active with authLevel system, service, or service_ext.
  • If no tags filter is provided, returns all secrets.
  • If tags filter is provided, returns only matching secrets.

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

tags (optional)

Array of secret tags to filter. If not provided, returns all secrets.

Returns

Returns array of secrets with decrypted values and metadata.

Path parameters
NameTypeDescription
tenantIdrequiredstringTenant identifier
communityIdrequiredstringCommunity identifier
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;
Request body
FieldTypeDescription
tagsarray<string>Optional array of secret tags to filter. If not provided, returns all secrets.
POSThttps://pilot-root.1kosmos.net/caas/tenants/{tenantId}/community/{communityId}/secrets/fetch
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/caas/tenants/tenant_123/community/community_456/secrets/fetch' \
  -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 '{"tags": ["stripe_api_key", "sendgrid_api_key"]}'
RESPONSE
200
401
500
Secrets fetched successfully
{
  "secrets": [
    {
      "tag": "stripe_api_key",
      "value": "sk_test_4eC39HqLyjWDarjtT1zdp7dc",
      "createdBy": "admin@example.com",
      "createdTs": 1704067200,
      "tenantId": "tenant_123",
      "communityId": "community_456"
    },
    {
      "tag": "sendgrid_api_key",
      "value": "decrypted_value_here",
      "createdBy": "admin@example.com",
      "createdTs": 1704067300,
      "tenantId": "tenant_123",
      "communityId": "community_456"
    }
  ]
}
PUT/tenants/{tenantId}/community/{communityId}/secrets

Create a new secret

Create a new secret with encrypted value storage.

  • Key must be active with authLevel system, service, or service_ext.
  • The combination of {tenantId, communityId, tag} must be unique.

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

tag (required)

Secret identifier. Must start with a letter [a-zA-Z] and contain only [a-zA-Z0-9_]

value (required)

Secret value to be encrypted and stored

createdBy (required)

User or service that created the secret

Returns

Returns secret metadata (tag, createdBy, createdTs) without the value.

This API throws an error if something goes wrong.

Path parameters
NameTypeDescription
tenantIdrequiredstringTenant identifier
communityIdrequiredstringCommunity identifier
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;
Request body
FieldTypeDescription
tagrequiredstringSecret identifier. Must start with a letter [a-zA-Z] and contain only [a-zA-Z0-9_]
valuerequiredstringSecret value to be encrypted and stored
createdByrequiredstringUser or service that created the secret
PUThttps://pilot-root.1kosmos.net/caas/tenants/{tenantId}/community/{communityId}/secrets
cURL
Node.js
Python
curl -X PUT 'https://pilot-root.1kosmos.net/caas/tenants/tenant_123/community/community_456/secrets' \
  -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 '{"tag": "stripe_api_key", "value": "sk_test_4eC39HqLyjWDarjtT1zdp7dc", "createdBy": "admin@example.com"}'
RESPONSE
201
400
401
409
500
Secret created successfully
{
  "tag": "stripe_api_key",
  "createdBy": "admin@example.com",
  "createdTs": 1704067200
}
DELETE/tenants/{tenantId}/community/{communityId}/secrets/{tag}

Delete a secret by tag

Delete a secret by its tag identifier.

  • Key must be active with authLevel system, service, or service_ext.
  • Once deleted, the secret cannot be recovered.

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 success message.

This API throws an error if the secret is not found.

Path parameters
NameTypeDescription
tenantIdrequiredstringTenant identifier
communityIdrequiredstringCommunity identifier
tagrequiredstringSecret identifier to delete
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;
DELETEhttps://pilot-root.1kosmos.net/caas/tenants/{tenantId}/community/{communityId}/secrets/{tag}
cURL
Node.js
Python
curl -X DELETE 'https://pilot-root.1kosmos.net/caas/tenants/tenant_123/community/community_456/secrets/stripe_api_key' \
  -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'
RESPONSE
200
401
404
500
Secret deleted successfully
{
  "message": "Secret deleted successfully"
}
Config & Consent

Service Directory

Service Directory endpoints.

GET/sd

Get all service directories.

Get all service directories.

If the API is call on internal path OR internal_sd=true then it will return internal URLs If the API is call on external_sd=true then it will return external URLs

Returns

Returns all service directories.

Query parameters
NameTypeDescription
internal_sdbooleaninternal_sd is used to generate internal URLs.
external_sdbooleanexternal_sd is used to generate external URLs.
GEThttps://pilot-root.1kosmos.net/caas/sd
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/caas/sd?internal_sd=True&external_sd=True' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
{
  "name1": "https://xxx.xxxxxx.xxx/xxxxx",
  "name2": "https://xxx.xxxxxx.xxx/xxxxx",
  "name3": "https://xxx.xxxxxx.xxx/xxxxx"
}
PATCH/sd

Create, update or delete service directories.

Create, update, delete service directories.

  • Key must be active with authLevel system.
  • Set empty string, null or false to remove service directory.
  • licenses service directory is not allowed to be removed.

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

JSON (required)

The JSON object to create, update or remove existing service directories.

Returns

Returns the all updated service directories.

This API throws an error if something goes wrong.

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;
Request body
FieldTypeDescription
name1string—
name2string—
name3string—
PATCHhttps://pilot-root.1kosmos.net/caas/sd
cURL
Node.js
Python
curl -X PATCH 'https://pilot-root.1kosmos.net/caas/sd' \
  -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 '{"name1": "https://xxx.xxxxxx.xxx/xxxxx", "name2": "https://xxx.xxxxxx.xxx/xxxxx", "name3": "https://xxx.xxxxxx.xxx/xxxxx"}'
RESPONSE
200
400
401
All updated service directories.
// no response body
Config & Consent

ECDSA Helper

ECDSA Helper endpoints.

POST/ecdsa_helper/{method}

/ecdsa_helper/{method}

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/caas/ecdsa_helper/{method}
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/caas/ecdsa_helper/<method>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -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"
}
Config & Consent

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/caas/healthz
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/caas/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
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"
}
Config & Consent

Public Key

Public Key endpoints.

GET/publickeys

/publickeys

Get system's public key.

Returns

Returns a public key object

GEThttps://pilot-root.1kosmos.net/caas/publickeys
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/caas/publickeys' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
401
{
  "publicKey": ""
}
© 2026 1Kosmos · NodeJS CaaS service v2.1Generated from the OpenAPI spec · caas.json