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

Headers

Header	Value
`Authorization`	`Bearer <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

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 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

Header	Value
`Authorization`	`Bearer <YOUR_API_KEY>`

Path Parameters

Parameter	Description
`<API_KEY_ID>`	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 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

Header	Value
`Authorization`	`Bearer <YOUR_API_KEY>`

Path Parameters

Parameter	Description
`<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

Header	Value
`Authorization`	`Bearer <YOUR_API_KEY>`

Path Parameters

Parameter	Description
`<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

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

Path Parameters

Parameter	Description
`<API_KEY_ID>`	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 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"
}'