1Kosmos · Session Management

Sessions API

Coordinate authentication sessions across devices — the backbone of QR-code and push-to-mobile login.

The Session Management service coordinates authentication sessions across devices — the backbone of QR-code and push-to-mobile login. Create a session on one device, complete it on another, poll for the result, and manage session attributes and lifecycle.

12 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 Sessions 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/sessions

Content type

Requests and responses use application/json.

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

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

Security

Authentication

Sessions 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

licenseLicense key from License Microserviceheader

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

cURL

Node.js

Python

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

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

import requests

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

Reference

Errors

Sessions 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"
}

Sessions

Session

Create, complete, poll and manage authentication sessions.

GET/nonce/validate

Validate Signature

Parameters

nonce (required)

The id of tenant

Returns

Returns signed nonce JSON

Query parameters

Name	Type	Description
noncerequired	string	Nonce string to validate

GEThttps://pilot-root.1kosmos.net/sessions/nonce/validate

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/sessions/nonce/validate?nonce=<nonce>' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/sessions/nonce/validate?nonce=<nonce>", {
  method: "GET",
  headers: {
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/sessions/nonce/validate?nonce=<nonce>",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

400

401

Signed nonce JSON

{
  "nonce": "string",
  "publicKey": "string",
  "generated_ts": "string",
  "valid_ts": "string"
}

// no response body

// no response body

GET/session/{sessionId}

Get info about session id

Returns AuthSession Object

Parameters

sessionId (required)

The id of session

Returns

Returns AuthSession object

Path parameters

Name	Type	Description
sessionIdrequired	string	Id of session to get info

GEThttps://pilot-root.1kosmos.net/sessions/session/{sessionId}

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/sessions/session/<sessionId>' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY' \
  -H 'license: YOUR_LICENSE_KEY'

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

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/sessions/session/<sessionId>",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

404

422

Session Info

{}

// no response body

// no response body

GET/session/{sessionId}/response

Fetch session response

Get info about AuthSessionEvent.

valid community license with authlevel system, service, service_ext, app and app_ext
sessionId must not be expired
caller's publicKey must match SessionAuth.publicKey
return associated SessionAuthResponse
note:
SessionAuthResponse object must get deleted after successfuly fetch
If session has expired, return appropriate error/message and delete both AuthSession and SessionAuthResponse entries.

Parameters

sessionId (required)

The id of session

Headers

addsessioninfo (optional)

If this header is set then the response will include "sessionInfo"

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 associated SessionAuthResponse object.

Path parameters

Name	Type	Description
sessionIdrequired	string	Id of session to submit auth data

Headers

Name	Type	Description
addsessioninfo	string	If this header is set then the response will include "sessionInfo" once the response returns successfully
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 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒

GEThttps://pilot-root.1kosmos.net/sessions/session/{sessionId}/response

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/sessions/session/xxxxxx-xxxxxx-xxxxx-xxxxx/response' \
  -H 'addsessioninfo: <value>' \
  -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/sessions/session/xxxxxx-xxxxxx-xxxxx-xxxxx/response", {
  method: "GET",
  headers: {
    "addsessioninfo": "<value>",
    "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/sessions/session/xxxxxx-xxxxxx-xxxxx-xxxxx/response",
    headers={
        "addsessioninfo": "<value>",
        "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

400

401

404

422

Session response

{}

// no response body

// no response body

// no response body

// no response body

POST/session/{sessionId}/authenticate

Authenticate session id

Authenticate session

There must be a AuthSession with sessionId
The AuthSession must not be expired
only auth SessionAuthEvent can be recorded against a session
note: (feb2): the "id" is mongo record Id

Parameters

sessionId (required)

The id of session

Request Body

did (required)

(TBD)

ial (optional)

(TBD)

eventData (optional)

(TBD)

appid (required)

(TBD)

data (required)

(TBD)

publicKey (required)

The publicKey is type of string and required.

Returns

Returns the session id (mongo record id) if the session auth event not exist. This API throws an error if something goes wrong. A common source of error is a session auth event is exists or auth session not existed(sessionId from params).

Path parameters

Name	Type	Description
sessionIdrequired	string	Id of session to submit auth data

Request body

New session data

Field	Type	Description
datarequired	string	—
appidrequired	string	—
ial	string	—
eventData	string	—
publicKeyrequired	string	—
didrequired	string	—

POSThttps://pilot-root.1kosmos.net/sessions/session/{sessionId}/authenticate

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/sessions/session/<sessionId>/authenticate' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": "xxxxxxxx", "appid": "xxxxxxxx", "ial": "xxxxxxxx", "eventData": "xxxxxxxx", "publicKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "did": "xxxxxx/xxxxxxxx"}'

const res = await fetch("https://pilot-root.1kosmos.net/sessions/session/<sessionId>/authenticate", {
  method: "POST",
  headers: {
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "data": "xxxxxxxx",
    "appid": "xxxxxxxx",
    "ial": "xxxxxxxx",
    "eventData": "xxxxxxxx",
    "publicKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "did": "xxxxxx/xxxxxxxx"
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/sessions/session/<sessionId>/authenticate",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "data": "xxxxxxxx",
      "appid": "xxxxxxxx",
      "ial": "xxxxxxxx",
      "eventData": "xxxxxxxx",
      "publicKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "did": "xxxxxx/xxxxxxxx"
    },
)
print(res.json())

RESPONSE

200

400

401

404

Session Info

{
  "id": "string"
}

// no response body

// no response body

// no response body

POST/tenant/{tenantId}/community/{communityId}/nonce/sign

Generate Signature

Parameters

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

publicKey (required)

caller's publicKey

nonce (required)

uuid

Returns

Returns signed nonce

Path parameters

Name	Type	Description
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": {
        "publicKey": "string - required",
        "nonce": "string - required"
    }
}

Field	Type	Description
data	object	—

POSThttps://pilot-root.1kosmos.net/sessions/tenant/{tenantId}/community/{communityId}/nonce/sign

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/sessions/tenant/<tenantId>/community/<communityId>/nonce/sign' \
  -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": {"publicKey": "xxxx", "nonce": "xxxx"}}'

const res = await fetch("https://pilot-root.1kosmos.net/sessions/tenant/<tenantId>/community/<communityId>/nonce/sign", {
  method: "POST",
  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": {
      "publicKey": "xxxx",
      "nonce": "xxxx"
    }
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/sessions/tenant/<tenantId>/community/<communityId>/nonce/sign",
    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": {
        "publicKey": "xxxx",
        "nonce": "xxxx"
      }
    },
)
print(res.json())

RESPONSE

200

400

401

Signed nonce

{
  "signed_nonce": "string"
}

// no response body

// no response body

PUT/session/new

Create a new session

Creates a new AuthSession object.

valid community license with authlevel system, service, service_ext, app and app_ext
create a new sessionId = new uuid()
create entry into the DB
publicKey is in the request headers
return created sessionId

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

origin (required)

The origin key is type of object and required

### Origin Child Parameters

tag (required) The tag key is type of string and required.

url (required) The url key is type of string and required.

communityName (required) The communityName key is type of string and required.

communityId (required) The communityId key is type of string and required.

authPage (optional) The authPage key is type of string and optional.

scopes (optional)

The scopes key is type of string and optional.

authtype (required)

The authtype key is type of string and required.

metadata (optional)

The metadata key is type of object and optional.

Returns

Returns created sessionId

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 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒

Request body

New session data

Field	Type	Description
originrequired	object	—
scopes	string	—
authtyperequired	string	—
metadata	object	—

PUThttps://pilot-root.1kosmos.net/sessions/session/new

cURL

Node.js

Python

curl -X PUT 'https://pilot-root.1kosmos.net/sessions/session/new' \
  -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 '{"origin": {"tag": "tagName", "url": "url", "communityName": "communityName", "communityId": "community id", "authPage": "string"}, "scopes": "string", "authtype": "string", "metadata": {}}'

const res = await fetch("https://pilot-root.1kosmos.net/sessions/session/new", {
  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({
    "origin": {
      "tag": "tagName",
      "url": "url",
      "communityName": "communityName",
      "communityId": "community id",
      "authPage": "string"
    },
    "scopes": "string",
    "authtype": "string",
    "metadata": {}
  })
});
const data = await res.json();

import requests

res = requests.put(
    "https://pilot-root.1kosmos.net/sessions/session/new",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY"
    },
    json={
      "origin": {
        "tag": "tagName",
        "url": "url",
        "communityName": "communityName",
        "communityId": "community id",
        "authPage": "string"
      },
      "scopes": "string",
      "authtype": "string",
      "metadata": {}
    },
)
print(res.json())

RESPONSE

201

400

401

403

404

422

// no response body

// no response body

// no response body

// no response body

// no response body

// no response body

Sessions

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/sessions/ecdsa_helper/{method}

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/sessions/ecdsa_helper/<method>' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY' \
  -H 'license: 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/sessions/ecdsa_helper/<method>", {
  method: "POST",
  headers: {
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY",
    "license": "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/sessions/ecdsa_helper/<method>",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY",
        "license": "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"
}

Sessions

Environment

Environment endpoints.

GET/environment

/environment

Provide details regarding the environments.

The system key whose type is hawk can only retrieve the environments.

Returns

Returns a environment object

Headers

### license License key

Headers

Name	Type	Description
license	string	License key;

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

cURL

Node.js

Python

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

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

import requests

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

RESPONSE

200

Success

// no response body

Sessions

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

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

cURL

Node.js

Python

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

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

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/sessions/healthz",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY",
        "license": "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 } ```

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

Sessions

Legacy Session

Backward-compatible session handoff.

PUT/api/r1/community/{communityName}/session/{sessionId}/authenticate

LEGACY - Authenticate session id

Submit auth data (legacy support)

There must be a AuthSession with sessionId
The AuthSession must not be expired
only auth SessionAuthEvent can be recorded against a session
note: (feb2): the "id" is mongo record Id

Parameters

sessionId (required)

The id of session

communityName (required)

The name of community (TBD - Ignore now => from spec file)

Request Body

did (required)

(TBD)

ial (optional)

(TBD)

appid (required)

(TBD)

data (required)

(TBD)

publicKey (required)

The publicKey is type of string and required.

Returns

Path parameters

Name	Type	Description
communityNamerequired	string	The name of community => Ignore now (TBD - you can input everything here)
sessionIdrequired	string	Id of session to submit auth data

Request body

New session data

Field	Type	Description
datarequired	string	—
appidrequired	string	—
ial	string	—
eventData	string	—
publicKeyrequired	string	—
didrequired	string	—

PUThttps://pilot-root.1kosmos.net/sessions/api/r1/community/{communityName}/session/{sessionId}/authenticate

cURL

Node.js

Python

curl -X PUT 'https://pilot-root.1kosmos.net/sessions/api/r1/community/<communityName>/session/<sessionId>/authenticate' \
  -H 'authMyPublicKey: YOUR_PUBLIC_KEY' \
  -H 'authMyPrivateKey: YOUR_PRIVATE_KEY' \
  -H 'authLicense: YOUR_LICENSE_KEY' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": "xxxxxxxx", "appid": "xxxxxxxx", "ial": "xxxxxxxx", "eventData": "xxxxxxxx", "publicKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "did": "xxxxxx/xxxxxxxx"}'

const res = await fetch("https://pilot-root.1kosmos.net/sessions/api/r1/community/<communityName>/session/<sessionId>/authenticate", {
  method: "PUT",
  headers: {
    "authMyPublicKey": "YOUR_PUBLIC_KEY",
    "authMyPrivateKey": "YOUR_PRIVATE_KEY",
    "authLicense": "YOUR_LICENSE_KEY",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "data": "xxxxxxxx",
    "appid": "xxxxxxxx",
    "ial": "xxxxxxxx",
    "eventData": "xxxxxxxx",
    "publicKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "did": "xxxxxx/xxxxxxxx"
  })
});
const data = await res.json();

import requests

res = requests.put(
    "https://pilot-root.1kosmos.net/sessions/api/r1/community/<communityName>/session/<sessionId>/authenticate",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "data": "xxxxxxxx",
      "appid": "xxxxxxxx",
      "ial": "xxxxxxxx",
      "eventData": "xxxxxxxx",
      "publicKey": "xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "did": "xxxxxx/xxxxxxxx"
    },
)
print(res.json())

RESPONSE

200

400

401

404

Session Info

{
  "id": "string"
}

// no response body

// no response body

// no response body

Sessions

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/sessions/publickeys

cURL

Node.js

Python

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

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

import requests

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

RESPONSE

200

404

{
  "publicKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

// no response body

Sessions

Service Directory

Service Directory endpoints.

GET/sd

Get all service directories.

Returns

Returns all service directories.

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

cURL

Node.js

Python

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

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

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/sessions/sd",
    headers={
        "authMyPublicKey": "YOUR_PUBLIC_KEY",
        "authMyPrivateKey": "YOUR_PRIVATE_KEY",
        "authLicense": "YOUR_LICENSE_KEY",
        "license": "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"
}