1Kosmos · Authorization

AuthZ API

Govern what an authenticated identity is allowed to do — roles, fine-grained permissions and real-time decisions.

The AuthZ service governs what an authenticated identity is allowed to do. Define roles, attach fine-grained permissions, and make real-time authorization decisions for your own applications and for the 1Kosmos platform itself.

20 endpoints

across 8 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 AuthZ 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/authz

Content type

Requests and responses use application/json.

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

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

Security

Authentication

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

Credentials

keyIdECDSA Public Keyheader

keySecretECDSA Private Keyheader

licenseLicense key from License Microserviceheader

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

cURL

Node.js

Python

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

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

import requests

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

Reference

Errors

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

AuthZ

Role

Create and manage roles.

GET/role/{id}

Fetch the specified role id.

Fetch for the specified role id..

Only a system and service key can be used to fetch role by id.

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 the fetched role.

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
idrequired	string	id of Role

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 🔒

GEThttps://pilot-root.1kosmos.net/authz/role/{id}

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/authz/role/xxxxxxxxxxxxxxxx' \
  -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'

const res = await fetch("https://pilot-root.1kosmos.net/authz/role/xxxxxxxxxxxxxxxx", {
  method: "GET",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/authz/role/xxxxxxxxxxxxxxxx",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

400

401

404

Success Fetched role: ``` { "id": "xxxxxxxxxxxxxxxxxxxx", "name": "xxxxxxxxxxxxxxxxxxxx", "description": "xxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx", "permissions": "[xxxxx, xxxxx]", "tenantId": "xxxxxxx", "communityId": "xxxxxxxxxxxxxxxxxxxx" } ```

{
  "id": "string",
  "name": "string",
  "description": "string",
  "createdBy": "string",
  "permissions": [
    "string"
  ],
  "tenantId": "string",
  "communityId": "string"
}

// no response body

// no response body

// no response body

POST/roles/fetch

Fetch Roles using tenant Id or community Id

Roles will be searched based on either the tenantId or communityId

Only a system and service key can be used to fetch roles.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Returns

Returns the matching roles.

This API throw an error if something goes wrong.

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

The tenant Id or community Id.

Only one of these two values will be used.

{
    "tenantId": "string optional, tenant's id",
    "communityId": "string optional, community's id"
}

Field	Type	Description
tenantId	string	—
communityId	string	—

POSThttps://pilot-root.1kosmos.net/authz/roles/fetch

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/authz/roles/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 '{"tenantId": "string", "communityId": "string"}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/roles/fetch", {
  method: "POST",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "tenantId": "string",
    "communityId": "string"
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/authz/roles/fetch",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "tenantId": "string",
      "communityId": "string"
    },
)
print(res.json())

RESPONSE

200

400

401

404

Success Fetched role: ``` [{ "id": "xxxxxxxxxxxxxxxxxxxx", "name": "xxxxxxxxxxxxxxxxxxxx", "description": "xxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx", "permissions": "[xxxxx, xxxxx]", "tenantId": "xxxxxxx", "communityId": "xxxxxxxxxxxxxxxxxxxx" }] ```

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "createdBy": "string",
    "permissions": [
      "string"
    ],
    "tenantId": "string",
    "communityId": "string"
  }
]

// no response body

// no response body

// no response body

PUT/role/

Create role.

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

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

name (required)

name of role

description (optional)

Description of role

createdBy (required)

User's uid who is creating permission, when a system-level key is used createdBy is optional otherwise it is required.

permissions (optional)

Array of Permission.id, an empty array is acceptable

tenantId (required)

Tenant's id on which this role is applicable

communityId (required)

Community's id on which this role is applicable

Returns

Returns the created role.

This API throw an error if something goes wrong.

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

Role to create.

{
    "name": "string required, name of role",
    "description": "string optional - description",
    "createdBy": "string conditional, IFF system-level key used - createdBy is optional else required",
    "permissions": "array optional - list of permission ids",
    "tenantId": "string required - tenant id",
    "communityId": "string required - community id"
}

Field	Type	Description
name	string	—
description	string	—
createdBy	string	—
permissions	array<string>	—
tenantId	string	—
communityId	string	—

PUThttps://pilot-root.1kosmos.net/authz/role/

cURL

Node.js

Python

curl -X PUT 'https://pilot-root.1kosmos.net/authz/role/' \
  -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 '{"name": "string", "description": "string", "createdBy": "string", "permissions": ["string"], "tenantId": "string", "communityId": "string"}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/role/", {
  method: "PUT",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "string",
    "description": "string",
    "createdBy": "string",
    "permissions": [
      "string"
    ],
    "tenantId": "string",
    "communityId": "string"
  })
});
const data = await res.json();

import requests

res = requests.put(
    "https://pilot-root.1kosmos.net/authz/role/",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "name": "string",
      "description": "string",
      "createdBy": "string",
      "permissions": [
        "string"
      ],
      "tenantId": "string",
      "communityId": "string"
    },
)
print(res.json())

RESPONSE

200

400

401

409

500

Success Created role: ``` { "id": "xxxxxxxxxxxxxxxxxxxx", "name": "xxxxxxxxxxxxxxxxxxxx", "description": "xxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx", "permissions": "[xxxxx, xxxxx]", "tenantId": "xxxxxxx", "communityId": "xxxxxxxxxxxxxxxxxxxx" } ```

{
  "id": "string",
  "name": "string",
  "description": "string",
  "createdBy": "string",
  "permissions": [
    "string"
  ],
  "tenantId": "string",
  "communityId": "string"
}

// no response body

// no response body

// no response body

// no response body

PATCH/role/{id}/permissions

Update the permissions for the specified role id.

Update the permissions for the specified role id..

If array length of set_list is greater than zero, then values in add_list and remove_list will be ignored.

If array length of add_list and array length of remove_list are both greater than zero, then add_list will be first added followed by remove_list.

Only a system and service key can be used to update the permissions.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

add_list (optional)

list of permissions to add to role

remove_list (optional)

list of permissions to remove from role

set_list (optional)

list of permissions to reset to role, i.e. existing permission will be replaced with the provided list

Returns

Returns the created role.

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
idrequired	string	id of Role

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

Permission to create.

{
    "add_list": "array optional, list of permissions to add",
    "remove_list": "array optional, list of permissions to remove",
    "set_list": "array optional, list of permissions to reset to",
}

Field	Type	Description
add_list	array<string>	—
remove_list	array<string>	—
set_list	array<string>	—

PATCHhttps://pilot-root.1kosmos.net/authz/role/{id}/permissions

cURL

Node.js

Python

curl -X PATCH 'https://pilot-root.1kosmos.net/authz/role/xxxxxxxxxxxxxxxx/permissions' \
  -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 '{"add_list": ["string"], "remove_list": ["string"], "set_list": ["string"]}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/role/xxxxxxxxxxxxxxxx/permissions", {
  method: "PATCH",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "add_list": [
      "string"
    ],
    "remove_list": [
      "string"
    ],
    "set_list": [
      "string"
    ]
  })
});
const data = await res.json();

import requests

res = requests.patch(
    "https://pilot-root.1kosmos.net/authz/role/xxxxxxxxxxxxxxxx/permissions",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "add_list": [
        "string"
      ],
      "remove_list": [
        "string"
      ],
      "set_list": [
        "string"
      ]
    },
)
print(res.json())

RESPONSE

200

400

401

404

Success Updated role: ``` { "id": "xxxxxxxxxxxxxxxxxxxx", "name": "xxxxxxxxxxxxxxxxxxxx", "description": "xxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx", "permissions": "[xxxxx, xxxxx]", "tenantId": "xxxxxxx", "communityId": "xxxxxxxxxxxxxxxxxxxx" } ```

{
  "id": "string",
  "name": "string",
  "description": "string",
  "createdBy": "string",
  "permissions": [
    "string"
  ],
  "tenantId": "string",
  "communityId": "string"
}

// no response body

// no response body

// no response body

PATCH/roles/name/{name}/permissions

Update the permissions for the specified role name.

If array length of set_list is greater than zero, then values in add_list and remove_list will be ignored.

If array length of add_list and array length of remove_list are both greater than zero, then add_list will be first added followed by remove_list.

Only a system and service key can be used to update the permissions.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

add_list (optional)

list of permissions to add to role

remove_list (optional)

list of permissions to remove from role

set_list (optional)

list of permissions to reset to role, i.e. existing permission will be replaced with the provided list

Returns

Returns the list of successfully updated roles.

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
namerequired	string	name of Role

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

Permission to create.

{
    "add_list": "array optional, list of permissions to add",
    "remove_list": "array optional, list of permissions to add",
    "set_list": "array optional, list of permissions to add",
}

Field	Type	Description
add_list	array<string>	—
remove_list	array<string>	—
set_list	array<string>	—

PATCHhttps://pilot-root.1kosmos.net/authz/roles/name/{name}/permissions

cURL

Node.js

Python

curl -X PATCH 'https://pilot-root.1kosmos.net/authz/roles/name/xxxxxxxxxxxxxxxx/permissions' \
  -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 '{"add_list": ["string"], "remove_list": ["string"], "set_list": ["string"]}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/roles/name/xxxxxxxxxxxxxxxx/permissions", {
  method: "PATCH",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "add_list": [
      "string"
    ],
    "remove_list": [
      "string"
    ],
    "set_list": [
      "string"
    ]
  })
});
const data = await res.json();

import requests

res = requests.patch(
    "https://pilot-root.1kosmos.net/authz/roles/name/xxxxxxxxxxxxxxxx/permissions",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "add_list": [
        "string"
      ],
      "remove_list": [
        "string"
      ],
      "set_list": [
        "string"
      ]
    },
)
print(res.json())

RESPONSE

200

400

401

404

Success Updated role: ``` [{ "id": "xxxxxxxxxxxxxxxxxxxx", "name": "xxxxxxxxxxxxxxxxxxxx", "description": "xxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx", "permissions": "[xxxxx, xxxxx]", "tenantId": "xxxxxxx", "communityId": "xxxxxxxxxxxxxxxxxxxx" }] ```

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "createdBy": "string",
    "permissions": [
      "string"
    ],
    "tenantId": "string",
    "communityId": "string"
  }
]

// no response body

// no response body

// no response body

DELETE/role/{id}

Delete the role with the specified role id.

Delete the role with the specified role id..

Only a system and service key can be used to delete role.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Path parameters

Name	Type	Description
idrequired	string	id of Role

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 🔒

DELETEhttps://pilot-root.1kosmos.net/authz/role/{id}

cURL

Node.js

Python

curl -X DELETE 'https://pilot-root.1kosmos.net/authz/role/xxxxxxxxxxxxxxxx' \
  -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'

const res = await fetch("https://pilot-root.1kosmos.net/authz/role/xxxxxxxxxxxxxxxx", {
  method: "DELETE",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.delete(
    "https://pilot-root.1kosmos.net/authz/role/xxxxxxxxxxxxxxxx",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

204

400

401

404

Success

// no response body

// no response body

// no response body

// no response body

AuthZ

Permission (Deprecated)

Legacy permission management (superseded by roles).

GET/permission/find/objects/{permission}/{subjectType}/{subjectId}

Fetch permission objects for a given subject.

Any valid key can be used to fetch permissions.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Returns

Returns the list of permissions for given subject.

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
permissionrequired	string	Permission for subject, tenant-admin or community-admin or authorized.
subjectTyperequired	string	Type of subject, tenant or community.
subjectIdrequired	string	ID of subject.

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 🔒

GEThttps://pilot-root.1kosmos.net/authz/permission/find/objects/{permission}/{subjectType}/{subjectId}

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/authz/permission/find/objects/xxxxxx-xxxxx/xxxxxx/xxxxxxxxxxxxxxxxxxxxxxxx' \
  -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'

const res = await fetch("https://pilot-root.1kosmos.net/authz/permission/find/objects/xxxxxx-xxxxx/xxxxxx/xxxxxxxxxxxxxxxxxxxxxxxx", {
  method: "GET",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/authz/permission/find/objects/xxxxxx-xxxxx/xxxxxx/xxxxxxxxxxxxxxxxxxxxxxxx",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

400

401

Success Permission objects for subject: ``` [ { "_id": "xxxxxxxxxxxxxxxxxxxx", "objectId": "xxxxxxxxxxxxxxxxxxxx", "objectType": "xxxx", "subjectId": "xxxxxxxxxxxxxxxxxxxx", "subjectType": "xxxxxx", "permission": "xxxxxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx" } ] ```

[
  {
    "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "objectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "objectType": "xxxxx",
    "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "subjectType": "xxxxxx",
    "permission": "xxxxxx-xxxxx",
    "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
]

// no response body

// no response body

POST/permission/check

Check permissions.

Any valid key can be used to fetch permissions.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

array (required)

Array of permissions to check.

Returns

Returns permission status.

This API throw an error if something goes wrong.

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

POSThttps://pilot-root.1kosmos.net/authz/permission/check

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/authz/permission/check' \
  -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 '[{"objectId": "xxxxxxxxxxxxxxxxxxxxxxxx", "objectType": "xxxxx", "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx", "subjectType": "xxxxxx", "permission": "xxxxxx-xxxxx"}]'

const res = await fetch("https://pilot-root.1kosmos.net/authz/permission/check", {
  method: "POST",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      "objectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "objectType": "xxxxx",
      "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "subjectType": "xxxxxx",
      "permission": "xxxxxx-xxxxx"
    }
  ])
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/authz/permission/check",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json=[
      {
        "objectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
        "objectType": "xxxxx",
        "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
        "subjectType": "xxxxxx",
        "permission": "xxxxxx-xxxxx"
      }
    ],
)
print(res.json())

RESPONSE

200

400

401

Success Permission status: ``` { status: true } ```

{
  "status": true
}

// no response body

// no response body

POST/permission/fetch

Fetch permissions.

Any valid key can be used to fetch permissions.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

array (required)

Array of permissions to fetch.

Returns

Returns the list of permissions.

This API throw an error if something goes wrong.

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 🔒

POSThttps://pilot-root.1kosmos.net/authz/permission/fetch

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/authz/permission/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 '[{"objectId": "xxxxxxxxxxxxxxxxxxxxxxxx", "objectType": "xxxxx", "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx", "subjectType": "xxxxxx"}]'

const res = await fetch("https://pilot-root.1kosmos.net/authz/permission/fetch", {
  method: "POST",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      "objectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "objectType": "xxxxx",
      "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "subjectType": "xxxxxx"
    }
  ])
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/authz/permission/fetch",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json=[
      {
        "objectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
        "objectType": "xxxxx",
        "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
        "subjectType": "xxxxxx"
      }
    ],
)
print(res.json())

RESPONSE

200

400

401

Success Fetched permissions: ``` [ { "_id": "xxxxxxxxxxxxxxxxxxxx", "objectId": "xxxxxxxxxxxxxxxxxxxx", "objectType": "xxxx", "subjectId": "xxxxxxxxxxxxxxxxxxxx", "subjectType": "xxxxxx", "permission": "xxxxxxxxxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx" } ] ```

[
  {
    "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "objectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "objectType": "xxxxx",
    "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "subjectType": "xxxxxx",
    "permission": "xxxxxx-xxxxx",
    "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
]

// no response body

// no response body

PUT/permission/create

Create permission.

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

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

objectId (required)

ID of object.

objectType (required)

Type of object, user or group.

subjectId (required)

ID of subject.

subjectType (required)

Type of subject, tenant or community.

permission (required)

Type of permission, tenant-admin, community-admin or authorized.

createdBy (conditional)

User's uid who is creating permission, when a system-level key is used createdBy is optional otherwise it is required.

Returns

Returns the created permission.

This API throw an error if something goes wrong.

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

Permission to create.

{
    "objectId": "string required, id of object",
    "objectType": "string required - user or group",
    "subjectId": "string required, id of subject",
    "subjectType": "string required - tenant or community",
    "permission": "string required - tenant-admin or community-admin or authorized",
    "createdBy": "string conditional, IFF system-level key used - createdBy is optional else required"
}

Field	Type	Description
objectId	string	—
objectType	string	—
subjectId	string	—
subjectType	string	—
permission	string	—
createdBy	string	—

PUThttps://pilot-root.1kosmos.net/authz/permission/create

cURL

Node.js

Python

curl -X PUT 'https://pilot-root.1kosmos.net/authz/permission/create' \
  -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 '{"objectId": "xxxxxxxxxxxxxxxxxxxxxxxx", "objectType": "xxxxx", "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx", "subjectType": "xxxxxx", "permission": "xxxxxx-xxxxx", "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/permission/create", {
  method: "PUT",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "objectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "objectType": "xxxxx",
    "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "subjectType": "xxxxxx",
    "permission": "xxxxxx-xxxxx",
    "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  })
});
const data = await res.json();

import requests

res = requests.put(
    "https://pilot-root.1kosmos.net/authz/permission/create",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "objectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "objectType": "xxxxx",
      "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "subjectType": "xxxxxx",
      "permission": "xxxxxx-xxxxx",
      "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
)
print(res.json())

RESPONSE

200

400

401

409

Success Created permission: ``` { "_id": "xxxxxxxxxxxxxxxxxxxx", "objectId": "xxxxxxxxxxxxxxxxxxxx", "objectType": "xxxx", "subjectId": "xxxxxxxxxxxxxxxxxxxx", "subjectType": "xxxxx", "permission": "xxxxxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx" } ```

{
  "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "objectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "objectType": "xxxxx",
  "subjectId": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "subjectType": "xxxxxx",
  "permission": "xxxxxx-xxxxx",
  "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

// no response body

// no response body

// no response body

DELETE/permission/{permissionId}

Delete permission.

Only a system and service key can be used to delete permission.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Parameters

No Parameters

Returns

No content.

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
permissionIdrequired	string	ID of permission

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 🔒

DELETEhttps://pilot-root.1kosmos.net/authz/permission/{permissionId}

cURL

Node.js

Python

curl -X DELETE 'https://pilot-root.1kosmos.net/authz/permission/xxxxxxxxxxxxxxxxxxxxxxxx' \
  -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'

const res = await fetch("https://pilot-root.1kosmos.net/authz/permission/xxxxxxxxxxxxxxxxxxxxxxxx", {
  method: "DELETE",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.delete(
    "https://pilot-root.1kosmos.net/authz/permission/xxxxxxxxxxxxxxxxxxxxxxxx",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

204

400

401

404

Success Empty response

// no response body

// no response body

// no response body

// no response body

AuthZ

Authorization

Evaluate authorization decisions at runtime.

POST/authorization/fetch

Fetch authorization.

Only a system and service key can be used to fetch authorization.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

objectType (required)

type of object (valid values user, licensekey)

objectId (required)

sha512(license) | uid of the User who is being given the authorization

subjectType (required)

type of subject (valid values tenant | community )

subjectId (required)

tid | cid of the tenant or community id

Returns

Returns the created authorization.

This API throw an error if something goes wrong.

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

Fetch Authorization

{
    "objectType": "string required - object type (valid values: user, licensekey)",
    "objectId": "string required - sha512(license) | uid of the User who is being given the authorization",
    "subjectType": "string required - type of subject (valid values tenant | community )",
    "subjectId": "string required - tid | cid of the tenant or community id",
}

Field	Type	Description
objectType	string	—
objectId	string	—
subjectType	string	—
subjectId	string	—

POSThttps://pilot-root.1kosmos.net/authz/authorization/fetch

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/authz/authorization/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 '{"objectType": "string", "objectId": "string", "subjectType": "string", "subjectId": "string"}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/authorization/fetch", {
  method: "POST",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "objectType": "string",
    "objectId": "string",
    "subjectType": "string",
    "subjectId": "string"
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/authz/authorization/fetch",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "objectType": "string",
      "objectId": "string",
      "subjectType": "string",
      "subjectId": "string"
    },
)
print(res.json())

RESPONSE

200

400

401

409

Success Fetched authorization: ``` [{ "id": "xxxxxxxxxxxxxxxxxxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx", "objectType": "xxxx", "objectId": "xxxxxxxxxxxxxxxxxxxx", "subjectType": "xxxxx", "subjectId": "xxxxxxx", "roleId": "xxxxxxxxxxxxxxxxxxxx", "role": { "name": "xxxxxxxxxxxxxxxxxxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx", "permissions": [ "xxxxx", "xxxxx" ], "tenantId": "xxxxxxxxxxxxxx", "communityId": "xxxxxxxxxxxxxxxx" } }] ```

{
  "items": {
    "id": "string",
    "createdBy": "string",
    "objectType": "string",
    "objectId": "string",
    "subjectType": "string",
    "subjectId": "string",
    "roleId": "string",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "createdBy": "string",
      "permissions": [
        "string"
      ],
      "tenantId": "string",
      "communityId": "string"
    }
  }
}

// no response body

// no response body

// no response body

PUT/authorization/

Create authorization.

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

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

createdBy (optional)

User's uid who is creating permission, when a system-level key is used createdBy is optional otherwise it is required.

objectType (required)

type of object (valid values user, licensekey)

objectId (required)

sha512(license) | uid of the User who is being given the authorization

subjectType (required)

type of subject (valid values tenant | community )

subjectId (required)

tid | cid of the tenant or community id

roleId (required)

roleId of the role

eventDetails (optional)

Additional details that are needed for the event

Returns

Returns the created authorization.

This API throw an error if something goes wrong.

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

Create Authorization

{
    "createdBy": "string conditional, IFF system-level key used - createdBy is optional else required",
    "objectType": "string required - object type (valid values: user, licensekey)",
    "objectId": "string required - sha512(license) | uid of the User who is being given the authorization",
    "subjectType": "string required - type of subject (valid values tenant | community )",
    "subjectId": "string required - tid | cid of the tenant or community id",
    "roleId": "string required - roleId of the role",
    "eventDetails":  "object optional - Additional details that are needed for the event"
}

Field	Type	Description
createdBy	string	—
objectType	string	—
objectId	string	—
subjectType	string	—
subjectId	string	—
roleId	string	—
eventDetails	object	—

PUThttps://pilot-root.1kosmos.net/authz/authorization/

cURL

Node.js

Python

curl -X PUT 'https://pilot-root.1kosmos.net/authz/authorization/' \
  -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 '{"createdBy": "string", "objectType": "string", "objectId": "string", "subjectType": "string", "subjectId": "string", "roleId": "string", "eventDetails": {}}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/authorization/", {
  method: "PUT",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "createdBy": "string",
    "objectType": "string",
    "objectId": "string",
    "subjectType": "string",
    "subjectId": "string",
    "roleId": "string",
    "eventDetails": {}
  })
});
const data = await res.json();

import requests

res = requests.put(
    "https://pilot-root.1kosmos.net/authz/authorization/",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "createdBy": "string",
      "objectType": "string",
      "objectId": "string",
      "subjectType": "string",
      "subjectId": "string",
      "roleId": "string",
      "eventDetails": {}
    },
)
print(res.json())

RESPONSE

200

400

401

409

Success Created authorization: ``` { "id": "xxxxxxxxxxxxxxxxxxxx", "createdBy": "xxxxxxxxxxxxxxxxxxxx", "objectType": "xxxx", "objectId": "xxxxxxxxxxxxxxxxxxxx", "subjectType": "[xxxxx, xxxxx]", "subjectId": "xxxxxxx", "roleId": "xxxxxxxxxxxxxxxxxxxx" } ```

{
  "id": "string",
  "createdBy": "string",
  "objectType": "string",
  "objectId": "string",
  "subjectType": "string",
  "subjectId": "string",
  "roleId": "string"
}

// no response body

// no response body

// no response body

DELETE/authorization/{authorizationId}

Delete authorization by id

Delete authorization by id.

Only a system and service key can be used to delete authorization by id.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

eventDetails (optional)

Additional details that are needed for the event

Returns

None

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
authorizationIdrequired	string	id of Authorization

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

Create Authorization

{
    "eventDetails":  "object optional - Additional details that are needed for the event"
}

Field	Type	Description
eventDetails	object	—

DELETEhttps://pilot-root.1kosmos.net/authz/authorization/{authorizationId}

cURL

Node.js

Python

curl -X DELETE 'https://pilot-root.1kosmos.net/authz/authorization/xxxxxxxxxxxxxxxx' \
  -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 '{"eventDetails": {}}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/authorization/xxxxxxxxxxxxxxxx", {
  method: "DELETE",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "eventDetails": {}
  })
});
const data = await res.json();

import requests

res = requests.delete(
    "https://pilot-root.1kosmos.net/authz/authorization/xxxxxxxxxxxxxxxx",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "eventDetails": {}
    },
)
print(res.json())

RESPONSE

204

400

401

404

Success Delete authorization:

// no response body

// no response body

// no response body

// no response body

DELETE/authorizations

Delete all authorizations matching filter based on objectType+objectId or subjectType+subjectId

Delete all authorizations matching filter based on objectType+objectId or subjectType+subjectId.

Only a system and service key can be used to delete all authorizations.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

objectType (required)

type of object (valid values user)

objectId (required)

uid of the User who is being given the authorization

subjectType (required)

type of subject (valid values tenant | community )

subjectId (required)

tid | cid of the tenant or community id

Returns

None.

This API throw an error if something goes wrong.

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

Delete all authorizations matching filter based on objectType+objectId or subjectType+subjectId

{
    "objectType": "string required - object type",
    "objectId": "string required, uid of the User who is being given the authorization",
    "subjectType": "string required - type of subject (valid values tenant | community )",
    "subjectId": "string required - tid | cid of the tenant or community id",
}

Field	Type	Description
objectType	string	—
objectId	string	—
subjectType	string	—
subjectId	string	—

DELETEhttps://pilot-root.1kosmos.net/authz/authorizations

cURL

Node.js

Python

curl -X DELETE 'https://pilot-root.1kosmos.net/authz/authorizations' \
  -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 '{"objectType": "string", "objectId": "string", "subjectType": "string", "subjectId": "string"}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/authorizations", {
  method: "DELETE",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "objectType": "string",
    "objectId": "string",
    "subjectType": "string",
    "subjectId": "string"
  })
});
const data = await res.json();

import requests

res = requests.delete(
    "https://pilot-root.1kosmos.net/authz/authorizations",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "objectType": "string",
      "objectId": "string",
      "subjectType": "string",
      "subjectId": "string"
    },
)
print(res.json())

RESPONSE

204

400

401

404

// no response body

// no response body

// no response body

// no response body

AuthZ

ECDSA Helper

ECDSA Helper endpoints.

POST/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
dataStr	string	—
publicKey	string	—
privateKey	string	—

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

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/authz/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="}'

const res = await fetch("https://pilot-root.1kosmos.net/authz/ecdsa_helper/<method>", {
  method: "POST",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "dataStr": "Hey, This is example data string.",
    "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=",
    "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/authz/ecdsa_helper/<method>",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "dataStr": "Hey, This is example data string.",
      "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=",
      "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="
    },
)
print(res.json())

RESPONSE

200

successful operation

{
  "data": "xxxxxxxxxxxxxxxxxxxx"
}

AuthZ

Environment

Environment endpoints.

GET/environment

/environment

Provide details regarding the environments.

Returns

Returns an environment object

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

cURL

Node.js

Python

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

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

import requests

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

RESPONSE

200

Success

// no response body

AuthZ

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/authz/healthz

cURL

Node.js

Python

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

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

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/authz/healthz",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "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"
}

AuthZ

Public Key

Public Key endpoints.

GET/publickeys

Get system's public key.

Returns

Returns a public key object

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

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/authz/publickeys' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

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

import requests

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

RESPONSE

200

401

{
  "publicKey": ""
}

// no response body

AuthZ

Service Directory

Service Directory endpoints.

GET/sd

Get all service directories.

Returns

Returns all service directories.

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

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/authz/sd' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

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

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/authz/sd",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "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"
}