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.

Before using this endpoint, you'll want to create your first API Key using Studio. Please review Getting Started for more information.

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

Requirements: User must have api_key:read permission.

Headers

Header	Value
`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 Example

List API Keys

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

Create an API Key

Endpoint: /apikeys

Method: POST

Requirements: User must have api_key:create permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_API_KEY>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
name	`string`	The name of the API key.
type	`ApiKeyTypes`	The type `sk` for a secret key.
role	`ProjectRoles`	The role of the API key. This determines the permissions that the API key has.
expires_at	`Date`	The 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 Example

Create API Key

curl --location --request POST '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

Requirements: User must have api_key:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_API_KEY>`

Path Parameters

Parameter	Data Type	Description
API_KEY_ID (Required)	`string`	The ID of the API key.

Query Parameters

Parameter	Data Type	Description
withValue	`boolean`	Whether to include the API key value in the response. This is only applicable for secret keys.

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 Example

Get API Key

curl --location --request GET '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

Requirements: User must have api_key:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_API_KEY>`

Path Parameters

Parameter	Data Type	Description
API_KEY_ID (Required)	`string`	The ID of the API key.

Example Response

{
  "token": "<API_KEY_TOKEN>"
}

Code Example

Get API Key Token

curl --location --request GET '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

Requirements: User must have api_key:delete permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_API_KEY>`

Path Parameters

Parameter	Data Type	Description
API_KEY_ID (Required)	`string`	The ID of the API key to delete.

Example Response

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

Code Example

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

Requirements: User must have api_key:update permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_API_KEY>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Data Type	Description
API_KEY_ID (Required)	`string`	The ID of the API key to update.

Input Parameters

Parameter	Data Type	Description
name	`string`	The name of the API key.
role	`ProjectRoles`	The role of the API key. This determines the permissions that the API key has.
enabled	`boolean`	Whether the API key is enabled or disabled.
expires_at	`Date`	The 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 Example

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