API keys — API reference

Managing the credentials of this account.

Generated from openapi.yaml at build time. Base URL https://api.tenergy.me/v1, or https://api-nile.tenergy.me/v1 on Nile (Environments). Every request below is signed as in Authentication unless its Auth line says otherwise.

List the keys of this account

GET /v1/api-keys · listApiKeys

Auth: API key (HMAC).

Secrets are never returned by this endpoint — a secret exists in a response exactly once, at creation. The key shown here is the public identifier sent in X-API-KEY.

Responses

Response fields

Create an API key

POST /v1/api-keys · createApiKey

Auth: API key (HMAC) or bootstrap token.

Creates a key and returns its secret once. The secret is not stored in a recoverable form; if it is lost, delete the key and create another.

The first key of an account is created with the bootstrap token from the signup flow; every later one with an existing key that itself holds keys.create.

Also on an unfunded account (since 2026-09-26), so an integration can read its deposit address with the new key and top up without a human in the loop.

scopes is required and has no default. The API deliberately does not invent a starter set of permissions: a key’s reach is a decision for the account owner, taken with the list in front of them. A request without scopes is rejected with 2001 validation_failed, and no client library, agent flow or dashboard form may supply one on the owner’s behalf.

One permission vocabulary

Permissions are named area.action and there is one list of names for the whole platform. The names below are the ones an API key may carry in v1. The remaining names in that vocabulary — balance.withdraw, billing.write, invoices.read, referral.read, referral.withdraw, team.read, team.invite, team.remove, team.grant, settings.write, audit.read — exist for use elsewhere in the platform (team management in the dashboard) but are not key-eligible in v1.

GET /ledger, GET /account/addresses and GET /session/history are dashboard-session operations and no scope opens them to a key.

A key can only be created with scopes that the creating key itself holds, so keys.create cannot be used to escalate beyond what the caller already has. A key created with the bootstrap token may carry any key-eligible scope, because the signing address is the account’s owner.

Request body

JSON (ApiKeyRequest), required.

Example request body, from the contract (illustrative values):

{
  "label": "grafana exporter",
  "scopes": ["balance.read","orders.read"],
  "ip_allowlist": ["203.0.113.10"]
}

Responses

Response fields

Edit a key

PATCH /v1/api-keys/{keyId} · updateApiKey

Auth: API key (HMAC).

Change label, ip_allowlist, is_active, or scopes. Narrowing scopes takes effect immediately. Widening them is subject to the same rule as creation: the calling key must already hold every scope being granted.

Parameters

Request body

JSON (ApiKeyPatch), required.

Responses

Response fields (ApiKey)

Revoke a key

DELETE /v1/api-keys/{keyId} · deleteApiKey

Auth: API key (HMAC).

Immediate and irreversible. In-flight requests signed with this key start failing at once; orders it already created are unaffected and keep running.

A key cannot delete itself — that would leave an account with no way back in if it were the last one. Revoking your own key is done from the dashboard.

Parameters

Responses