1Kosmos · License Management

Licensing API

Issue, authorize and rotate the license keys behind every service.

The License Management service issues and authorizes the license keys that gate every other 1Kosmos service. Mint service keys, manage key authorizations, and rotate credentials.

14 endpoints

across 5 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 Licensing 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/licenses

Content type

Requests and responses use application/json.

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

curl -X GET 'https://pilot-root.1kosmos.net/licenses/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'licensekey: YOUR_LICENSE_KEY'

Security

Authentication

Licensing 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

keyIdHawk Key Id / ECDSA Public Keyheader

keySecretHawk Key Secret / ECDSA Private Keyheader

licensekeyAPI Public Keyheader

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

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/licenses/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'licensekey: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/licenses/healthz", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "licensekey": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/licenses/healthz",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "licensekey": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

Reference

Errors

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

Licensing

Service Key

Mint and rotate service keys.

GET/servicekey

Get Service Key details by Id or tag

Retrieves the details of an existing service key.

If the signing key is a system key, any keys can be requested.

If the signing key is a service key, all but system keys can be requested.

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

Parameters

keyId (required)

The keyId or tag of service key.

Returns

Returns a service key object if a valid keyId was provided.

Query parameters

Name	Type	Description
keyId	string	—

Headers

Name	Type	Description
privateKeyrequired	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 / Try Authorize 🔒
systemPublicKeyrequired	string	Public Key / Try Authorize 🔒

GEThttps://pilot-root.1kosmos.net/licenses/servicekey

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/licenses/servicekey?keyId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx' \
  -H 'privateKey: YOUR_PRIVATE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'systemPublicKey: <value>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'licensekey: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/licenses/servicekey?keyId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", {
  method: "GET",
  headers: {
    "privateKey": "YOUR_PRIVATE_KEY",
    "requestid": "<ecdsa-requestid>",
    "systemPublicKey": "<value>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "licensekey": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/licenses/servicekey?keyId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    headers={
        "privateKey": "YOUR_PRIVATE_KEY",
        "requestid": "<ecdsa-requestid>",
        "systemPublicKey": "<value>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "licensekey": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

401

404

Service key fetch successfully

{
  "_id": "xxxxxxxxxxxxxxxxxxxx",
  "type": "xxxxx",
  "tag": "xxxxxxxx",
  "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
  "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
  "disabled": false,
  "expiry": "2023-01-13T15:36:44.978Z",
  "authLevel": "xxxxxxx",
  "module": {},
  "description": ""
}

// no response body

// no response body

GET/servicekey/current

Get Current User Service Key details

Retrieves the service key details of the current user.

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

Returns

Returns a service key object if a current user is authenticated.

Headers

Name	Type	Description
privateKeyrequired	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 / Try Authorize 🔒
systemPublicKeyrequired	string	Public Key / Try Authorize 🔒

GEThttps://pilot-root.1kosmos.net/licenses/servicekey/current

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/licenses/servicekey/current' \
  -H 'privateKey: YOUR_PRIVATE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'systemPublicKey: <value>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'licensekey: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/licenses/servicekey/current", {
  method: "GET",
  headers: {
    "privateKey": "YOUR_PRIVATE_KEY",
    "requestid": "<ecdsa-requestid>",
    "systemPublicKey": "<value>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "licensekey": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/licenses/servicekey/current",
    headers={
        "privateKey": "YOUR_PRIVATE_KEY",
        "requestid": "<ecdsa-requestid>",
        "systemPublicKey": "<value>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "licensekey": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

401

Success

{
  "_id": "xxxxxxxxxxxxxxxxxxxx",
  "type": "xxxxx",
  "tag": "xxxxxxxx",
  "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
  "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
  "disabled": false,
  "expiry": "2023-01-13T15:36:44.978Z",
  "authLevel": "xxxxxxx",
  "module": {},
  "description": ""
}

// no response body

POST/servicekey/fetch

Get All Service Keys

Returns a list of service keys.

When API is called using a system key, API will return all keys.

When API is called using a service key, API will return all but system keys.

[change] no otherkey is permitted to request ALL service keys.

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

Parameters

pIndex (optional)

The pIndex key is a cursor for the pagination.

pSize (optional)

A limit on the number of objects to be returned. The range between 1 to 25 and the default is 10.

Returns

Returns a list of service keys with pagination.

Query parameters

Name	Type	Description
pIndex	integer	—
pSize	integer	—

Headers

Name	Type	Description
privateKeyrequired	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 / Try Authorize 🔒
systemPublicKeyrequired	string	Public Key / Try Authorize 🔒

POSThttps://pilot-root.1kosmos.net/licenses/servicekey/fetch

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/licenses/servicekey/fetch?pIndex=0&pSize=10' \
  -H 'privateKey: YOUR_PRIVATE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'systemPublicKey: <value>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'licensekey: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/licenses/servicekey/fetch?pIndex=0&pSize=10", {
  method: "POST",
  headers: {
    "privateKey": "YOUR_PRIVATE_KEY",
    "requestid": "<ecdsa-requestid>",
    "systemPublicKey": "<value>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "licensekey": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/licenses/servicekey/fetch?pIndex=0&pSize=10",
    headers={
        "privateKey": "YOUR_PRIVATE_KEY",
        "requestid": "<ecdsa-requestid>",
        "systemPublicKey": "<value>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "licensekey": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

401

Success

{
  "page": {
    "index": 0,
    "total": 50,
    "size": 1
  },
  "data": [
    {
      "tag": "xxxxxxx",
      "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
      "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
      "disabled": false,
      "expiry": "2023-01-08T08:39:55.000Z",
      "authLevel": "xxxxxx",
      "modules": {}
    }
  ]
}

// no response body

PUT/servicekey

Create Service Key

Creates a new service key object.

Only a system and a service key can be used to create a new key.

Only a system key can be used to create other system keys.

system and service key can create all other types.

No other key can be used to create a new key.

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

Request Body

tag (required)

A tag is alpha-numeric (a-z, A-Z, 0-9) unique identifier with some special character '-', '_', '|' and ':'.

keyId (optional)

The keyId is valid and unique key. The keyId is auto-generated as a uuid if keyId is not provided.

keySecret (required if keyId is provided)

The keySecret is valid and unique key. The keySecret is auto-generated as a uuid if keySecret is not provided.

disabled (optional)

The disabled key only accept these values (true, false). Default disabled value is false

expiry (optional)

Set the expiry date for the service key.

An expiry key is a valid future date.

Default expiry value is current date plus 2 years.

authLevel (optional)

This key defines the authentications level of the service key. The authLevel value must be a valid auth level. The authLevel key only accept these values ("system", "service", "service_ext", "app_ext", "app", "basic")

Default authLevel value is "basic"!

type (optional)

This key defines the authentication type of the service key. The type key only accept these values ('hawk', 'ecdsa', 'user')

Default type value is Hawk. When using type = user, keyId should be user's URN. keySecret can be any value as it's internally over-written.

modules (optional object)

Default modules value is empty object({}).

### Modules Child Parameters

mod_dl (optional) The mod_dl key is type of boolean and optional.

mod_identity (optional) The mod_identity key is type of boolean and optional.

mod_pp (optional) The mod_pp key is type of boolean and optional.

mod_face (optional) The mod_face key is type of boolean and optional.

mod_pin (optional) The mod_pin key is type of boolean and optional.

mod_nationalid (optional) The mod_nationalid key is type of boolean and optional.

mod_core (optional) The mod_core key is type of boolean and optional.

mod_misc (optional) The mod_misc key is type of boolean and optional.

bypass_poi (optional) The bypass_poi key is type of boolean and optional.

mod_ssn (optional) The mod_ssn key is type of boolean and optional.

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

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

mod_email (optional) The mod_email key is type of boolean and optional.

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

description (optional)

This field use to add licensekey info

Returns

Returns the service key object if the service key object is created successfully.

This API throws an error if something goes wrong. A common source of error is tag, keyId and keySecret are already exists.

Headers

Name	Type	Description
privateKeyrequired	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 / Try Authorize 🔒
systemPublicKeyrequired	string	Public Key / Try Authorize 🔒

Request body

Field	Type	Description
tag	string	3-256 alpha-numeric (a-z, A-Z, 0-9), special character '-', '_', '\|' and ':'
keyId	string	auto-generated as a uuid
keySecret	string	auto-generated as a uuid
disabled	boolean	default = false
expiry	string	default current system time + 2 years
authLevel	string	options [ system, service, app, service_ext, app_ext, basic ] and default = basic
modules	object	—
description	string	—

PUThttps://pilot-root.1kosmos.net/licenses/servicekey

cURL

Node.js

Python

curl -X PUT 'https://pilot-root.1kosmos.net/licenses/servicekey' \
  -H 'privateKey: YOUR_PRIVATE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'systemPublicKey: <value>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"tag": "xxxxxxx", "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx", "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx", "disabled": false, "expiry": "2023-01-08T08:39:55.000Z", "authLevel": "xxxxxx", "modules": {}, "type": "hawk | ecdsa | user", "description": ""}'

const res = await fetch("https://pilot-root.1kosmos.net/licenses/servicekey", {
  method: "PUT",
  headers: {
    "privateKey": "YOUR_PRIVATE_KEY",
    "requestid": "<ecdsa-requestid>",
    "systemPublicKey": "<value>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "licensekey": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "tag": "xxxxxxx",
    "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "disabled": false,
    "expiry": "2023-01-08T08:39:55.000Z",
    "authLevel": "xxxxxx",
    "modules": {},
    "type": "hawk | ecdsa | user",
    "description": ""
  })
});
const data = await res.json();

import requests

res = requests.put(
    "https://pilot-root.1kosmos.net/licenses/servicekey",
    headers={
        "privateKey": "YOUR_PRIVATE_KEY",
        "requestid": "<ecdsa-requestid>",
        "systemPublicKey": "<value>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "licensekey": "YOUR_LICENSE_KEY"
    },
    json={
      "tag": "xxxxxxx",
      "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
      "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
      "disabled": false,
      "expiry": "2023-01-08T08:39:55.000Z",
      "authLevel": "xxxxxx",
      "modules": {},
      "type": "hawk | ecdsa | user",
      "description": ""
    },
)
print(res.json())

RESPONSE

200

401

Service key created successfully

{
  "_id": "xxxxxxxxxxxxxxxxxxxx",
  "type": "xxxxx",
  "tag": "xxxxxxxx",
  "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
  "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
  "disabled": false,
  "expiry": "2023-01-13T15:36:44.978Z",
  "authLevel": "xxxxxxx",
  "module": {},
  "description": ""
}

// no response body

PATCH/servicekey

Update Service Key details

Updates the specified service key with specified parameters, only provided parameters will be updated.

Only a system key can be used to update another system key.

system key can update all other types of key.

service key can update all other types of non-system key.

Only following attributes can be changed using this API.

disabled, expiry, modules

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

Parameters

keyId (required)

The keyId of service key.

Request Body

disabled (optional)

Disabled or Enabled service key. The disabled key only accept these values (true, false).

The value will be left unchanged if the disabled key is not provided.

expiry (optional)

Set the expiry date for the service key.

An expiry key is a valid future date.

The value will be left unchanged if the expiry key is not provided.

description (optional)

This field use to add licensekey info

modules (optional object)

The value will be left unchanged if the modules object is not provided.

### Modules Child Parameters