1Kosmos · Event Stream

Events API

Subscribe to and query identity events across your tenant.

The Events service is the platform's activity stream. Subscribe to and query identity events across your tenant for audit, analytics and real-time reaction.

8 endpoints

across 7 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 Events 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/events

Content type

Requests and responses use application/json.

GEThttps://pilot-root.1kosmos.net/events/healthz

curl -X GET 'https://pilot-root.1kosmos.net/events/healthz' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY'

Security

Authentication

Events 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

authMyPublicKeyCaller's ECDSA publicKeyheader

authMyPrivateKeyCaller's ECDSA privateKeyheader

authLicenseLicense key from License APIheader

GEThttps://pilot-root.1kosmos.net/events/healthz

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/events/healthz' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/events/healthz", {
  method: "GET",
  headers: {
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/events/healthz",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

Reference

Errors

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

Status	Meaning	Description
200 / 204	OK	The request succeeded.
400	Bad Request	Validation failed.
401	Unauthorized	Missing or invalid credentials.
403	Forbidden	Authenticated, but not permitted.
404	Not Found	The resource does not exist.
500	Server Error	Something went wrong on our side.

4XXerror response

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error"
}

Events

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 60 seconds from now

publickey (required)

Public key

Returns

Returns array with service keys

Headers

Name	Type	Description
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒
requestidrequired	string	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 60 seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒

GEThttps://pilot-root.1kosmos.net/events/servicekeys

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/events/servicekeys' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/events/servicekeys", {
  method: "GET",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/events/servicekeys",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

// no response body

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)

publickey (required)

Public key

Returns

Returns object with page info and data

Path parameters

Name	Type	Description
keyIdrequired	string	keyId of service key to reset

Headers

Name	Type	Description
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒
requestidrequired	string	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 60 seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒

DELETEhttps://pilot-root.1kosmos.net/events/servicekey/{keyId}

cURL

Node.js

Python

curl -X DELETE 'https://pilot-root.1kosmos.net/events/servicekey/<keyId>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/events/servicekey/<keyId>", {
  method: "DELETE",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.delete(
    "https://pilot-root.1kosmos.net/events/servicekey/<keyId>",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

204

// no response body

Events

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

Name	Type	Description
method	string	—

Request body

Field	Type	Description
dataStrrequired	string	Message to encrypt or decrypt
publicKeyrequired	string	—
privateKeyrequired	string	—

POSThttps://pilot-root.1kosmos.net/events/ecdsa_helper/{method}

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/events/ecdsa_helper/<method>' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dataStr": "Hey, This is example data string.", "publicKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "privateKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'

const res = await fetch("https://pilot-root.1kosmos.net/events/ecdsa_helper/<method>", {
  method: "POST",
  headers: {
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "dataStr": "Hey, This is example data string.",
    "publicKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "privateKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/events/ecdsa_helper/<method>",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY"
    },
    json={
      "dataStr": "Hey, This is example data string.",
      "publicKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "privateKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
)
print(res.json())

RESPONSE

200

Success

{
  "data": "xxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxx"
}

Events

Environment

Environment endpoints.

GET/environment

/environment

Returns

Headers

### licensekey License key

Headers

Name	Type	Description
licensekey	string	License key;

GEThttps://pilot-root.1kosmos.net/events/environment

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/events/environment' \
  -H 'licensekey: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/events/environment", {
  method: "GET",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/events/environment",
    headers={
        "licensekey": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

Success

// no response body

Events

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-seconds 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>``

Headers

Name	Type	Description
synthetic-heartbeat	string	If this field is set then additional health information is collection (will not be displayed).
licensekey	string	plain text license key (system level OR infra-key);

GEThttps://pilot-root.1kosmos.net/events/healthz

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/events/healthz' \
  -H 'synthetic-heartbeat: <value>' \
  -H 'licensekey: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/events/healthz", {
  method: "GET",
  headers: {
    "synthetic-heartbeat": "<value>",
    "licensekey": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/events/healthz",
    headers={
        "synthetic-heartbeat": "<value>",
        "licensekey": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

Success ``` { "status": "all services operational", "publicKey": "string" //same as <service>/publickeys endpoint, "code": "200", "version": "<version>", //as defined above "syntheticheartbeatId": "<syntheticheartbeatId>" } ```

{
  "status": "all services operational",
  "publicKey": "//same as <service>/publickeys endpoint",
  "code": "200",
  "version": "xxxx.xxxx.xxxx",
  "syntheticheartbeatId": "xxxxxxxx"
}

Events

Public Key

Public Key endpoints.

GET/publickeys

/publickeys

Get system's public key. No authorization

Returns

Returns a public key object

GEThttps://pilot-root.1kosmos.net/events/publickeys

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/events/publickeys' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/events/publickeys", {
  method: "GET",
  headers: {
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/events/publickeys",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

404

{
  "publicKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

// no response body

Events

Service Directory

Service Directory endpoints.

GET/sd

Get all service directories.

Returns

Returns all service directories.

GEThttps://pilot-root.1kosmos.net/events/sd

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/events/sd' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/events/sd", {
  method: "GET",
  headers: {
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/events/sd",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

{
  "name1": "https://xxx.xxxxxx.xxx/xxxxx",
  "name2": "https://xxx.xxxxxx.xxx/xxxxx",
  "name3": "https://xxx.xxxxxx.xxx/xxxxx"
}

Events

Tenant

Per-tenant event streams.

PUT/tenant/{tenantId}/community/{communityId}/event/{eventName}

Create Event

Creates an event in DB. You can send any number of fields in request body

Parameters

eventName (required)

The name of the event to log. Suggested values: E_USER_ONBOARDED, E_USER_INVITED, E_LOGIN_ATTEMPT, E_LOG_OTP_REQUESTED or different.

tenantId (required)

The id of tenant

communityId (required)

The id of community

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

type (required)

Event type

timestamp (optional)

Time of event in string that is able to be parsed as date

default = current time

epoch_time (optional)

Time of event in number

default = current time

Returns

Returns status code OK if everything is ok

Path parameters

Name	Type	Description
eventNamerequired	string	Name of event
tenantIdrequired	string	Id of tenant
communityIdrequired	string	Id of community

Headers

Name	Type	Description
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒
requestidrequired	string	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 60 seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒

Request body

Request body contains 'data' field with encrypted object below:

IMPORTANT - you can send unencrypted data in this request, it is only available in Swagger

{
    "data": {
        "type": "string - required",
        "epoch_time": "number in seconds - optional",
        "timestamp": "string in date format 'YYYY-MM-DD HH:mm:ss.SSS' or other readable - optional",
        ...restOfEventData
    }
}

Field	Type	Description
data	object	—

PUThttps://pilot-root.1kosmos.net/events/tenant/{tenantId}/community/{communityId}/event/{eventName}

cURL

Node.js

Python

curl -X PUT 'https://pilot-root.1kosmos.net/events/tenant/<tenantId>/community/<communityId>/event/<eventName>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"type": "event", "timestamp": "2023-02-14 15:00:00.000", "epoch_time": 1318781876}}'

const res = await fetch("https://pilot-root.1kosmos.net/events/tenant/<tenantId>/community/<communityId>/event/<eventName>", {
  method: "PUT",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "data": {
      "type": "event",
      "timestamp": "2023-02-14 15:00:00.000",
      "epoch_time": 1318781876
    }
  })
});
const data = await res.json();

import requests

res = requests.put(
    "https://pilot-root.1kosmos.net/events/tenant/<tenantId>/community/<communityId>/event/<eventName>",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY"
    },
    json={
      "data": {
        "type": "event",
        "timestamp": "2023-02-14 15:00:00.000",
        "epoch_time": 1318781876
      }
    },
)
print(res.json())

RESPONSE

200

400

403

// no response body

// no response body

// no response body