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 Types

The ApiKey type. Can be one of 'sk' or 'pk'.

sk (Secret Key): Must never be used from a public client like a browser page.
pk (Public Key): Can be used to access the API from anywhere (e.g. a browser page). This type of key can only read public data and execute interactions.

It is recommended to use key rotations to keep the keys secure. Public keys can be requested using a secret key on the server making the key rotation easy to implement.

Project Roles

The role an API key may have. Can be one of:

reader: Read only access to projects.
executor: Read only access and can execute interactions. This is the role used by a Public Key.
application: Like executor and in addition can request public keys too.
developer: Full access to objects inside projects but cannot delete objects.
admin: Can perform any action on the project.

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 of API key. This can be either `pk` for a public key or `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. This is only applicable for public keys.

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. This is only applicable for public keys.

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