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