> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit administration

> Read your organization's credit balance and grant manual credits as Erdo staff

## Read the current balance

```bash theme={null}
erdo --org harbor-view credits balance
```

This returns `balance`, `lifetime_purchased`, and `lifetime_consumed`. The organization
comes from your current login or `--org`; your credential must have access to it.
A manager key can read a managed organization's balance by selecting that organization.

The REST equivalent is `GET /v1/credits/balance`, with the organization slug or UUID
in `X-Organization-ID`. The MCP tool is `erdo_credit_balance`; it uses the session's
current organization. Balance reads do not expose another organization's billing data.

## Grant credits as staff

```bash theme={null}
erdo admin credits grant harbor-view --amount 1000 --reason "Support allocation"
```

Only an active human Erdo staff member or superuser can grant credits. Sign in with
`erdo login` as that staff user, or use their unrestricted personal API key.
An organization owner, administrator, or manager service principal cannot grant
credits. External scoped tokens and scoped or read-only API keys cannot grant them.
MCP does not accept scoped or read-only API keys, including for balance reads.

The positional target accepts an organization slug or UUID. It is separate from
`--org`, which selects the caller's authenticated organization. You can remain in
your staff organization while granting to a target organization.

`--amount` must be a positive integer, at most 2147483647; `--reason` must contain
text and is stored in the audit ledger. Grants add non-expiring credits without
charging a payment method. They do not change subscriptions, auto top-up, billing
ownership, or manager funding.

The response identifies the target and the balance committed with the grant:

```json theme={null}
{"organization_id":"<target-uuid>","amount":1000,"balance":1075}
```

Usage after the grant can change the balance. If you have access to the target,
read it again with `erdo --org harbor-view credits balance`.

### REST and MCP

`POST /v1/admin/credits/grant` accepts:

```json theme={null}
{"organization":"harbor-view","amount":1000,"reason":"Support allocation"}
```

The MCP tool `erdo_admin_grant_credits` takes `organization_slug`, `amount`, and
`reason`; its target must be a slug. REST and MCP call the canonical staff grant
service. The web admin's separate Top-up action adds credits that expire after
12 months.

> [!WARNING]
>
> Every invocation is a new grant. The CLI does not retry grant requests. If a
> connection drops, a response cannot be read, or a server error leaves the outcome
> unknown, do **not** repeat the command. Inspect the target organization's credit
> ledger under **Admin → Billing → Credits** for the target, amount, reason, and
> time first.
> A balance alone cannot prove whether a particular grant occurred because other
> credits and usage may change it. REST and MCP clients must also disable automatic
> replay of this mutation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.