Skip to main content

API Keys

Following endpoints facilitate API key rotation, for security reasons - current key gets stolen, user access needs to be revoked, organization expires, etc.\ It is good practice to rotate them every once in a while, regardless (e.g. every three months).

Fetch​

GET omni/api-key/

Fetch all API keys of current user's organization.\ If user is super admin, parameter apiKey can be provided to specify organization for which the keys should be fetched (ignored otherwise).

Parameters:

  • apiKey: String, optional. Organization reference.

Headers:

api-version: 1.0
x-api-key: <client-specific-key>
x-incode-hardware-id: <user-token>

Response:

  • name: String. Key name.
  • clientId: String. Key clientId, name + radnom 3 digits.
  • value: String. Key value, sha1(clientId).
  • valid: Boolean. Key validity.
  • createdAt: Long. Key creation timestamp.
  • updatedAt: Long. Key adjustment timestamp.

Example:

[
  {
    "name": "key1",
    "clientId": "key1254",
    "value": "f35844c8bcb417be1a64fd6e8d622cc93b0fcfaa",
    "valid": true,
    "createdAt": 1678185005948,
    "updatedAt": 1678185005948
  },
  {
    "name": "key2",
    "clientId": "key2869",
    "value": "f42844c8bcb417be1a64fd6e8d622cc93b0abcde",
    "valid": true,
    "createdAt": 1678185916715,
    "updatedAt": 1678185916715
  },
  {
    "name": "key3",
    "clientId": "key3352",
    "value": "f78844c8bcb417be1a64fd6e8d622cc93b0bcdef",
    "valid": false,
    "createdAt": 1678272368139,
    "updatedAt": 1678185824506
  }
]

Create​

POST omni/api-key/

Create new API key for current user's organization.\ If user is super admin, parameter apiKey can be provided to specify organization for which the key should be created (ignored otherwise).

Request:

  • name: String, mandatory. Key name.
  • apiKey: String, optional. Organization reference.

Headers:

api-version: 1.0
x-api-key: <client-specific-key>
x-incode-hardware-id: <user-token>

Example:

{
  "name": "key12",
  "apiKey": "6efbabe21a3b44955be51d25336fb7876b68a234"
}

Response:

  • name: String. Key name.
  • clientId: String. Key clientId, name + radnom 3 digits.
  • value: String. Key value, sha1(clientId).
  • valid: Boolean. Key validity.
  • createdAt: Long. Key creation timestamp.
  • updatedAt: Long. Key adjustment timestamp.

Example:

{
  "name": "key12",
  "clientId": "key12568",
  "value": "6efbabe21a3b44955be51d25336fb7876b68a567",
  "valid": true,
  "createdAt": 1678799487000,
  "updatedAt": 1678799487000
}

Update​

PUT omni/api-key/

Validate/invalidate API key for current user's organization.\ If user is super admin, parameter apiKey can be provided to specify organization for which the key should be adjusted (ignored otherwise).\ User is not allowed to invalidate last valid key of the belonging organization.\ Super admin user can invalidate last valid keys of other organizations (effectively revoking their access to the application).

Request:

  • name: String, mandatory. Key name.
  • valid: Boolean, mandatory. Key validity.
  • apiKey: String, optional. Organization reference.

Headers:

api-version: 1.0
x-api-key: <client-specific-key>
x-incode-hardware-id: <user-token>

Example:

{
  "name": "key12",
  "valid": false,
  "apiKey": "6efbabe21a3b44955be51d25336fb7876b68a234"
}

Response:

  • name: String. Key name.
  • clientId: String. Key clientId, name + radnom 3 digits.
  • value: String. Key value, sha1(clientId).
  • valid: Boolean. Key validity.
  • createdAt: Long. Key creation timestamp.
  • updatedAt: Long. Key adjustment timestamp.

Example:

{
  "name": "key12",
  "clientId": "key12568",
  "value": "6efbabe21a3b44955be51d25336fb7876b68a567",
  "valid": false,
  "createdAt": 1678799487000,
  "updatedAt": 1678799487000
}

Migration​

There used to be only one API key per organization, created and registered on API Gateway at the time of organization creation.\ Each organization has a user defined name, on which 3 random digits are added to generate clientId, on which sha1 was applied to generate apiKey.\ Field clientId was also used as organization identifier, while apiKey also served as organization reference.

With the rotatable approach, API key management is delegated to a separate collection, which would contain clientId and value for each record.\ This also enables having multiple API keys per organization.\ Fields clientId/apiKey on organization entity will keep their identifier/reference function, to maintain referential integrity between entities.

In order to facilitate the new approach and ensure backwards compatibility, a migration process is established.\ Through it, API key related fields are copied from Organization to RotatableApiKey collection, so that in the end each organization would have a corresponding rotatable key created.\ Key validity is checked on API Gateway directly (if applicable, otherwise set to true).\ All subsequent API key management would affect new collection only.