// reference · 6 min read

Accounts API

Every endpoint under /v1/accounts: provision a full account under your developer, list them, fetch one and close one. Authenticated with your rsk_ provisioning key. For the conceptual walkthrough and funding-mode guidance see the guide, Provision accounts for your customers. Every field, id shape and error code here is the real one from the route code.

Authentication

All /v1/accounts endpoints authenticate with your developer provisioning key: Authorization: Bearer rsk_<hex>. This is not a tenant ko_ key. Each developer has exactly one active rsk_ key; mint or rotate it from /app/developer. Every call is scoped to the accounts created under that key's developer.

The account object

Returned in full by the list and get endpoints. id is a UUID (the platform user id), not a prefixed id like cus_ or ko_.

Field	Type	Notes
`id`	string (UUID)	The account id. Use it as `{id}` on the get and delete endpoints.
`email`	string	Login email.
`username`	string	Login username (3-20 chars, alphanumeric or underscore).
`owner_type`	string	Always `api_end_user` for a provisioned account.
`status`	string	`active` or `closed`. A closed account cannot sign in and its `ko_` tokens are revoked.
`funding`	string	`linked` if the account bills your wallet, otherwise `standalone` (self / grant / voucher funded). The original sub-mode (self vs grant vs voucher) is not stored.
`balance_usd`	number	The account's own wallet balance. Always 0 for a `linked` account (it spends your wallet).
`spend_usd`	number	Lifetime spend from the account's own ledger. For a linked account this reads 0, because linked charges land on your developer ledger tagged with the account id.
`created_at`	timestamp	When the account was provisioned.
`closed_at`	timestamp \| null	When it was closed, or null if active.

POST /v1/accounts

Provision a new account under your developer. Subject to your active-account cap (default 10).

Field	Required	Notes
`email`	yes	Unique across the platform.
`username`	yes	3-20 chars, `[a-zA-Z0-9_]`. Unique across the platform.
`password`	yes	8-256 chars. The login password for the web UI.
`vault_password`	no	Defaults to `password`. Derives the account's vault key.
`funding`	no	`self` (default) \| `grant` \| `voucher` \| `linked`. See the guide for semantics.
`amount_usd`	with `grant`	Positive amount to move from your wallet to the new account.
`voucher_code`	with `voucher`	A voucher you minted (wallet-backed).

{
  "account": { "id": "<uuid>", "email": "dev@customer.com", "username": "customer_acme", "owner_type": "api_end_user" },
  "api_key": "ko_…",
  "api_key_prefix": "ko_xxxxxxx",
  "credit": { "balance_usd": 25.0, "funding": "grant", "applied": true, "reason": null },
  "message": "Your Ringside account is ready.\n  Sign in: https://ringside.fightclub.pro/login\n  …"
}

api_key is shown once

The api_key is the new account's own ko_ key, returned a single time. It is the account's credential, not yours. The full account object (with status and balances) is available any time from GET /v1/accounts/{id}.

GET /v1/accounts

List every account under your developer. Returns a list envelope of full account objects.

curl https://api.fightclub.pro/v1/accounts \
  -H "Authorization: Bearer rsk_REDACTED"

GET /v1/accounts/{id}

Fetch one account object. 404 account_not_found if the id is not an account under your developer.

DELETE /v1/accounts/{id}

Close (offboard) the account. This frees a cap slot, blocks the account's login and revokes its ko_ tokens immediately. 404 account_not_found if it is not an open account under your developer.

{ "id": "<uuid>", "object": "account", "status": "closed", "deleted": true }

Errors

Status	code	Cause
`401`	`invalid_provisioning_key`	Missing, malformed or revoked `rsk_` key.
`403`	`cap_reached`	At your active-account limit (create only).
`409`	`account_exists`	Email or username already in use (create only).
`402`	`insufficient_funds`	`funding: "grant"` but your wallet cannot cover `amount_usd`.
`404`	`account_not_found`	Get/delete on an id that is not an account under you (delete: not an open one).
`400`	`invalid_request`	A field failed validation, or the funding mode is missing its required input.
`429`	`rate_limited`	Too many provisioning calls on this key in the last minute (create).

·GET /v1/balance — the calling account's own balance. A linked account reports "billing": "linked" and does not expose the parent developer's wallet.
·Wallet-backed vouchers are minted from the developer dashboard (/app/developer); pass the resulting code as voucher_code on create.

Guide: Provision accounts for your customers →Metering and billing →Regions and data residency →

← Previous

Brain Packs API

Regions and data residency