API keys

An API key is a credential for a program rather than a person. It belongs to one organization, and it has a role and a set of scopes that limit what it can do.

What a key can do today

Only one operation accepts an API key today: listOrganizationMultiCurrencyAccounts, with the balances:read scope. Every other operation refuses a key with 403 api_key_not_permitted.

So for almost everything, your server calls Ele with a staff member’s session token, as described in Authentication. Ele will open more operations to keys over time, and this page will list them.

A key can never:

Pay, or approve anything.
Manage API keys.
Complete step-up, or call anything that needs it.

Using a key

Send the key as a bearer token, like a session token:

curl -s "$ELE_API_BASE/api/v1/organizations/$ORG_ID/multi-currency-accounts" \
  -H "Authorization: Bearer $ELE_API_KEY"

A key looks like ele_<env>_<lookup>_<secret>. env is live for production keys and test for sandbox keys; a key works only in its own environment. lookup is 8 characters that identify the key. Everything after it is the secret.

Treat the key like a password. Keep it in a secret store. Never log the whole key: log only the lookup.

Creating a key

An owner or admin of the organization creates a key with createApiKey, using their own session token. The call needs step-up.

curl -s "$ELE_API_BASE/api/v1/organizations/$ORG_ID/api-keys" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Balance sync", "role": "member", "scopes": ["balances:read"]}'

The response holds the secret. Ele shows it once and never again, so store it straight away. Ele does not store the response for idempotency, so a retry creates a second key. Do not retry this call automatically; if you are unsure whether it worked, list the keys with listApiKeys.

Give each key the narrowest role and scopes it needs. A key’s role cannot be higher than the role of the person who creates it.

Roles and scopes

A key’s role is admin or member. Its scopes name what it may do, and the role caps which scopes it may hold:

Scope	Lowest role that may hold it
`balances:read`	member
`events:read`	member
`events:subscribe`	member
`payment_requests:read`	member
`payment_requests:write`	member
`payments:read`	member
`transactions:read`	member
`refunds:write`	admin
`webhooks:manage`	admin

Only balances:read is used by an operation today. The others are reserved for operations that will accept keys later.

Change a key’s role or scopes with updateApiKey, which needs step-up.

Rotating a key

rotateApiKey gives a key a new secret and keeps its lookup. The old secret keeps working for 24 hours, so you can deploy the new one without downtime. Then stop using the old one.

Only the two latest secrets work. Rotating again within the 24 hours ends the older secret at once.

As with creating, the new secret is shown once, and a retry rotates again. Do not retry rotation automatically. If a secret must stop working now, revoke the key instead.

Revoking a key

revokeApiKey stops a key working at once. Revoke a key when you retire the program that uses it, or if its secret may have leaked. A revoked key cannot be rotated or updated; Ele answers 409 with the type api_key_revoked.

If Ele bans an organization, all its keys are revoked, and lifting the ban does not restore them.

Limits

An organization can have at most 50 active keys. Creating another returns 422 api_key_limit_reached. Revoke keys you no longer use.

Only owners and admins can see and manage an organization’s keys. To anyone else, a key’s ID is not found.

Errors

Status	`type`	Meaning
`401`	`invalid_api_key`	The key is malformed, unknown, revoked or for the other environment, or the secret does not match.
`403`	`api_key_not_permitted`	This operation does not accept API keys.
`403`	`api_scope_missing`	The key does not have the scope this operation needs.
`403`	`organization_unavailable`	The key’s organization is paused, banned or deleted.
`403`	`role_exceeds_creator`	The key’s role would be higher than yours.
`409`	`api_key_revoked`	You tried to change a revoked key.
`422`	`api_key_limit_reached`	The organization already has 50 active keys.