API Keys

The /apikeys endpoint is used to authenticate requests to the platform and access the restricted API. API Keys can be exchanged for JWT tokens to use other endpoints in the platform.

API Keys

An Api Key is a private secret that must never be used from a public client like a browser page. It is recommended to use key rotations to keep the keys secure.

Project Roles

The role an API key may have.

All roles and associated permissions can be found in Studio under the Settings for Users and Permissions.

List API Keys

Endpoint: /apikeys

Method: GET

Headers

HeaderValue
AuthorizationBearer <YOUR_API_KEY>

Example Request

curl --location 'https://api.vertesia.io/api/v1/apikeys' \
--header 'Authorization: Bearer <YOUR_API_KEY>'

Example Response

[
  {
    "id": "<API_KEY_ID>",
    "name": "My API Key",
    "type": "sk",
    "role": "developer",
    "maskedValue": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxx",
    "account": "<ACCOUNT_ID>",
    "project": "<PROJECT_ID>",
    "enabled": true,
    "created_by": "user:<USER_ID>",
    "updated_by": "user:<USER_ID>",
    "created_at": "2023-04-19T12:34:56.000Z",
    "updated_at": "2023-04-19T12:34:56.000Z",
    "expires_at": "2024-04-19T12:34:56.000Z"
  }
]

Code Examples

List API Keys

curl --location 'https://api.vertesia.io/api/v1/apikeys' \
--header 'Authorization: Bearer <YOUR_API_KEY>'

Create an API Key

Endpoint: /apikeys

Method: POST

Headers

HeaderValue
AuthorizationBearer <YOUR_API_KEY>
Content-Typeapplication/json

Input Parameters

ParameterData TypeDescription
namestringThe name of the API key.
typeApiKeyTypesThe type sk for a secret key.
roleProjectRolesThe role of the API key. This determines the permissions that the API key has.
expires_atDateThe date and time when the API key expires in ISO 8601 format.

Example Request

{
  "name": "My API Key",
  "type": "sk",
  "role": "developer",
  "expires_at": "2024-04-19T12:34:56.000Z"
}

Example Response

{
  "id": "<API_KEY_ID>",
  "name": "My API Key",
  "type": "sk",
  "role": "developer",
  "account": "<ACCOUNT_ID>",
  "project": "<PROJECT_ID>",
  "enabled": true,
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-04-19T12:34:56.000Z",
  "updated_at": "2023-04-19T12:34:56.000Z",
  "expires_at": "2024-04-19T12:34:56.000Z"
}

Code Examples

Create API Key

curl --location 'https://api.vertesia.io/api/v1/apikeys' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "My API Key",
  "type": "sk",
  "role": "developer",
  "expires_at": "2024-04-19T12:34:56.000Z"
}'

Get API Key

Endpoint: /apikeys/<API_KEY_ID>

Method: GET

Headers

HeaderValue
AuthorizationBearer <YOUR_API_KEY>

Path Parameters

ParameterDescription
<API_KEY_ID>The ID of the API key.

Query Parameters

ParameterData TypeDescription
withValuebooleanWhether to include the API key value in the response. This is only applicable for secret keys.

Example Request

curl --location 'https://api.vertesia.io/api/v1/apikeys/<API_KEY_ID>?withValue=true' \
--header 'Authorization: Bearer <YOUR_API_KEY>'

Example Response

{
  "id": "<API_KEY_ID>",
  "name": "My API Key",
  "type": "sk",
  "role": "developer",
  "value": "<API_KEY_VALUE>",
  "account": "<ACCOUNT_ID>",
  "project": "<PROJECT_ID>",
  "enabled": true,
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-04-19T12:34:56.000Z",
  "updated_at": "2023-04-19T12:34:56.000Z",
  "expires_at": "2024-04-19T12:34:56.000Z"
}

Code Examples

Get API Key

curl --location 'https://api.vertesia.io/api/v1/apikeys/<API_KEY_ID>?withValue=true' \
--header 'Authorization: Bearer <YOUR_API_KEY>'

Get API Key Token

Endpoint: /apikeys/<API_KEY_ID>/token

Method: GET

Headers

HeaderValue
AuthorizationBearer <YOUR_API_KEY>

Path Parameters

ParameterDescription
<API_KEY_ID>The ID of the API key.

Example Request

curl --location 'https://api.vertesia.io/api/v1/apikeys/<API_KEY_ID>/token' \
--header 'Authorization: Bearer <YOUR_API_KEY>'

Example Response

{
  "token": "<API_KEY_TOKEN>"
}

Code Examples

Get API Key Token

curl --location 'https://api.vertesia.io/api/v1/apikeys/<API_KEY_ID>/token' \
--header 'Authorization: Bearer <YOUR_API_KEY>'

Delete API Key

Endpoint: /apikeys/<API_KEY_ID>

Method: DELETE

Headers

HeaderValue
AuthorizationBearer <YOUR_API_KEY>

Path Parameters

ParameterDescription
<API_KEY_ID>The ID of the API key to delete.

Example Request

curl --location --request DELETE 'https://api.vertesia.io/api/v1/apikeys/<API_KEY_ID>' \
--header 'Authorization: Bearer <YOUR_API_KEY>'

Example Response

{
  "acknowledged": true,
  "deletedCount": 1
}

Code Examples

Delete API Key

curl --location --request DELETE 'https://api.vertesia.io/api/v1/apikeys/<API_KEY_ID>' \
--header 'Authorization: Bearer <YOUR_API_KEY>'

Update API Key

Endpoint: /apikeys/<API_KEY_ID>

Method: PUT

Headers

HeaderValue
AuthorizationBearer <YOUR_API_KEY>
Content-Typeapplication/json

Path Parameters

ParameterDescription
<API_KEY_ID>The ID of the API key to update.

Input Parameters

ParameterData TypeDescription
namestringThe name of the API key.
roleProjectRolesThe role of the API key. This determines the permissions that the API key has.
enabledbooleanWhether the API key is enabled or disabled.
expires_atDateThe date and time when the API key expires.

Example Request

{
  "name": "My Updated API Key",
  "role": "admin",
  "enabled": false,
  "expires_at": "2025-04-19T12:34:56.000Z"
}

Example Response

{
  "id": "<API_KEY_ID>",
  "name": "My Updated API Key",
  "type": "sk",
  "role": "admin",
  "account": "<ACCOUNT_ID>",
  "project": "<PROJECT_ID>",
  "enabled": false,
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-04-19T12:34:56.000Z",
  "updated_at": "2023-04-19T12:34:56.000Z",
  "expires_at": "2025-04-19T12:34:56.000Z"
}

Code Examples

Update API Key

curl --location --request PUT 'https://api.vertesia.io/api/v1/apikeys/<API_KEY_ID>' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "My Updated API Key",
  "role": "admin",
  "enabled": false,
  "expires_at": "2025-04-19T12:34:56.000Z"
}'

Was this page helpful?