Admin API Keys

This document outlines the process of generating and managing API keys for the Admin Service API.

1. Overview

API keys are unique identifiers used to authenticate requests to the Admin Service API. They function similarly to a password, granting access to your account's resources. When making a request, the API key must be included in the request header.

How to use API keys in requests (example using cURL):

You should include your API key in the X-Auth-Token or Authorization header of your HTTP requests.

curl -si \
  https://admin.hlx.page/.... \
  -H 'X-Auth-Token: YOUR_API_KEY_HERE'

Or

curl -si \
  https://admin.hlx.page/... \
  -H 'Authorization: token YOUR_API_KEY_HERE'

Key Expiration and Rotation:

For security best practices, API keys have an expiration period. It is crucial to rotate your API keys regularly to minimize the risk of unauthorized access if a key is compromised. We recommend setting up a process to generate new keys and replace the old ones before their expiration. This can be automated or done manually, depending on your operational needs.

Interoperability

When you successfully create a new API key or import an existing one, the key is automatically enabled for your Admin Service API. There is no need to manually add the API Key ID to the access.admin.apiKeyId property of the site configuration. Note that both API Key Id sources are respected, the key listed here and in the access.admin.apiKeyId property.

Permissions

In order to create, update or delete the keys, your request needs to be authenticated with an admin role.

2. Create

New API keys can be created by sending a POST request to the org, profile or site config of your project.

Endpoint: POST https://admin.hlx.page/config/{org}/sites/{site}/apiKeys.json

Request Body Example:

{
  "description": "API key for development environment",
  "roles": ["publish"]
}

Response Example (Success):

{
  "id": "newly_generated_key_id",
  "value": "your_new_api_key_value",
  "description": "API key for development environment",
  "created": "2023-10-27T10:00:00Z",
  "expiration": "2024-10-27T10:00:00Z"
}

Note: The value in the response is the actual API key. Store it securely as it will not be retrievable again through the API.

Note: The API key is never stored in our system and can not be retrieved at a later time.

3. Import

Existing API keys can be imported using the same /apiKeys.json endpoint as above, but by including a jwt payload property in the request body. This method is typically used for migrating existing keys.

Endpoint: POST https://admin.hlx.page/config/{org}/sites/{site}/apiKeys.json

Request Body Example:

{
  "description": "Imported API key for legacy system",
  "jwt": "YOUR_JWT_PAYLOAD_CONTAINING_KEY_INFO"
}

Note: The API key is never stored in our system and can not be retrieved at a later time.

4. List

You can retrieve a list of all existing API keys by sending a GET request to the org, profile or site config of your project.

Endpoint: GET https://admin.hlx.page/config/{org}/sites/{site}/apiKeys.json

R esponse Example:

{
  "key_id_1": {
    "id": "key_id_1",
    "description": "API key for production service",
    "created": "2023-01-15T09:30:00Z",
    "expiration": "2024-01-15T09:30:00Z"
  },
  "key_id_2": {
    "id": "key_id_2",
    "description": "API key for internal tooling",
    "created": "2023-03-20T14:00:00Z",
    "expiration": "2024-03-20T14:00:00Z"
  },
  "key_id_3": {
    "id": "key_id_3",
    "description": "API key for development environment",
    "created": "2023-10-27T10:00:00Z",
    "expiration": "2024-10-27T10:00:00Z"
  }
]

Note: For security reasons, the actual API key (value property) is not returned when listing keys. Only metadata about the keys is provided.

5. Update

To update the description of an existing API key, send a POST request to the respective config entry.

Endpoint: POST https://admin.hlx.page/config/{org}/sites/{site}/apiKeys/{id}.json

Request Body Example:

{
  "description": "Updated description for production API key"
}

Response Example (Success):

JSON

{
  "id": "existing_key_id",
  "description": "Updated description for production API key",
  "created": "2023-10-27T10:00:00Z",
  "expiration": "2024-10-27T10:00:00Z"
}

6. Delete

To delete an API key, send a DELETE request to the request to the respective config entry.

Endpoint: DELETE https://admin.hlx.page/config/{org}/sites/{site}/apiKeys/{id}.json