API keys — API reference

Managing the credentials of this account.

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.

Keys created by an AI agent (OAuth access token with api_keys.manage): a key that can spend (orders.create, subscriptions.write) gets the connected agent’s own daily and monthly limits when daily_limit_trx / monthly_limit_trx are omitted. A limit above the agent’s, or null while the agent has one, is refused with 403 3032 agent_key_limit_exceeded (details.grant_daily_limit_sun, details.grant_monthly_limit_sun). Only the account owner sets other limits, in the dashboard. Such a key shows created_by_agent.

Parameters

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.

An AI agent may only lower a key’s spend limits or set them within its own limits; it cannot remove one while it has a limit itself, nor add a spending scope to a key whose limits exceed its own. Otherwise 403 3032 agent_key_limit_exceeded.

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