API keys
Create, list, change, rotate and delete API keys.
See API keys. A key can only create or change keys with permissions it has itself.
Create a key
POST /v1/apiKeys.createKey
Creates an API key. The secret is in the response and can't be retrieved later.
Permissions: the key needs teral:v1:<workspace_id>:rootKeys/*#write.
Request
| Field | Type | Description |
|---|---|---|
name | string | A name to recognize the key by. At most 255 characters. |
permissions | string[], required | What the key may do. Each permission must be one the calling key has. 0 to 1000 items. |
expires | integer or null | When the key stops working, in Unix milliseconds. Must be in the future. null or leaving it out means it never expires, unless the calling key expires itself: then the new key must expire no later. |
curl -X POST https://api.teral.dev/v1/apiKeys.createKey \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "github-actions-deploy",
"permissions": [
"environment.*.create_deployment",
"environment.*.read_deployment"
]
}'Response
On success the status is 200 OK. The fields in data:
| Field | Type | Description |
|---|---|---|
keyId | string | The key's ID, for managing it. |
key | string | The secret. Store it now: it's never shown again. |
Error statuses: 400, 401, 403, 500. See Errors for the codes behind them.
List keys
POST /v1/apiKeys.listKeys
Returns the workspace's API keys without their secrets, a page at a time.
Permissions: the key needs teral:v1:<workspace_id>:rootKeys/<key_id>#read.
Request
| Field | Type | Description |
|---|---|---|
limit | integer | How many results to return in one page. Default 100. 1 to 100. |
cursor | string | The pagination.cursor of the previous response, to get the next page. At most 256 characters. |
curl -X POST https://api.teral.dev/v1/apiKeys.listKeys \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"limit": 50
}'Response
On success the status is 200 OK. The fields in data:
| Field | Type | Description |
|---|---|---|
keyId | string | The key's ID. |
name | string or null | The key's name, or null. |
start | string | The first characters of the secret, to recognize the key. |
end | string | The last characters of the secret. Empty for older keys. |
enabled | boolean | Whether the key is turned on. A key can be on and still expired. |
createdAt | integer | When it was created, in Unix milliseconds. |
lastUsedAt | integer | When the key was last used, in Unix milliseconds. 0 if never. At least 0. |
expires | integer or null | When the key expires, in Unix milliseconds, or null if it doesn't. |
permissions | string[] | Everything the key may do. |
When pagination.hasMore is true, pass pagination.cursor as cursor to get the next page.
Error statuses: 400, 401, 429, 500. See Errors for the codes behind them.
Update a key
POST /v1/apiKeys.updateKey
Changes a key's name, state or permissions. Fields you leave out stay as they are.
Permissions: the key needs teral:v1:<workspace_id>:rootKeys/<key_id>#write.
Request
| Field | Type | Description |
|---|---|---|
keyId | string, required | The key's ID. 3 to 255 characters. |
name | string or null | A new name. null removes it. 1 to 255 characters. |
enabled | boolean | Turns the key on or off. |
permissions | string[] | The complete new set of permissions, replacing the old one. 0 to 1000 items. |
curl -X POST https://api.teral.dev/v1/apiKeys.updateKey \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"keyId": "key_8sJ2…",
"enabled": false
}'Response
On success the status is 200 OK.
Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.
Rotate a key
POST /v1/apiKeys.rerollKey
Creates a new key with the same name, state, expiry and permissions, and returns its secret. Choose how long the old key keeps working, so you can switch over without downtime.
Permissions: the key needs one of teral:v1:<workspace_id>:rootKeys/<key_id>#write, teral:v1:<workspace_id>:rootKeys/<key_id>#delete.
Request
| Field | Type | Description |
|---|---|---|
keyId | string, required | The key to rotate. 3 to 255 characters. |
expiration | integer or null, required | How many milliseconds the old key keeps working. 0 revokes it now. null leaves its expiry as it is. It can only shorten an existing expiry. 0 to 4102444800000. |
curl -X POST https://api.teral.dev/v1/apiKeys.rerollKey \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"keyId": "key_8sJ2…",
"expiration": 3600000
}'Response
On success the status is 200 OK. The fields in data:
| Field | Type | Description |
|---|---|---|
keyId | string | The new key's ID. |
key | string | The new secret. Store it now: it's never shown again. |
Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.
Delete a key
POST /v1/apiKeys.deleteKey
Deletes an API key. Requests using it fail from then on.
Permissions: the key needs teral:v1:<workspace_id>:rootKeys/<key_id>#delete.
Request
| Field | Type | Description |
|---|---|---|
keyId | string, required | The key's ID. 3 to 255 characters. |
curl -X POST https://api.teral.dev/v1/apiKeys.deleteKey \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"keyId": "key_8sJ2…"
}'Response
On success the status is 200 OK.
Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.