# Users and licenses

> List accounts with their metrics, create licenses, and change fees, referrers, keys and status.

Admin endpoints manage Proxima accounts and their license keys. They need a JWT whose user has the admin role; other callers get `403`. The web app calls them from the `/admin` pages.

An account is identified by its stable `account_id`, which survives a key rotation and a rename. Rates are in basis points (1% = 100). `*_usd` amounts are micro-USD and `*_native` amounts are lamports or wei, all as integer strings.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `GET /admin/users`: List users
- `GET /admin/get-mints`: List licenses with launches
- `POST /admin/add-license`: Create a license
- `POST /admin/update-license`: Update a license
- `POST /admin/rotate-key`: Rotate a license key
- `POST /admin/set-key-active`: Activate or deactivate a license key
- `GET /admin/users/licenses`: List an account's licenses
- `POST /admin/tokens/read`: Create a read token

## The Admin user object

An account as listed in the admin users table, with its fees, trading metrics and referral position.

- `account_id` (string): Stable account id. It survives a key rotation and a rename; admin write endpoints identify accounts by it.
- `username` (string): Account username.
- `display_name` (string | null): Display name shown instead of `@username`.
- `avatar_url` (string | null): Avatar image URL.
- `license_key` (string): Current license key.
- `created_at` (integer): Creation time, Unix seconds.
- `tier` (string): License tier.
- `fee_rate` (integer): Sell fee, in basis points.
- `sell_fee_rate` (integer): Same value as `fee_rate`.
- `buy_fee_rate` (integer): Buy fee, in basis points.
- `cashback_rate` (integer): Share of what Proxima keeps on this account's launches, after referrals, paid back to it, in basis points.
- `is_active` (boolean): Whether the license key is active.
- `is_internal` (boolean): Internal account. Analytics populations leave internal accounts out.
- `launch_count` (integer): Number of launches.
- `pnl_usd` (string): Launch P&L, in micro-USD, as an integer string.
- `pnl_native` (string | null): Launch P&L, in lamports or wei, as an integer string. `null` when no `chain_id` filter is set and the account is active on several chains.
- `volume_sold_usd` (string): Volume sold, in micro-USD, as an integer string.
- `volume_sold_native` (string | null): Volume sold, in lamports or wei, as an integer string.
- `volume_bought_usd` (string): Volume bought, in micro-USD, as an integer string.
- `volume_bought_native` (string | null): Volume bought, in lamports or wei, as an integer string.
- `fees_paid_usd` (string): Fees paid to Proxima, in micro-USD, as an integer string.
- `fees_paid_native` (string | null): Fees paid to Proxima, in lamports or wei, as an integer string.
- `referral_paid_usd` (string): Referral paid out of this account's fees to its referrer chain, in micro-USD, as an integer string.
- `referral_paid_native` (string | null): Same as `referral_paid_usd`, in lamports or wei, as an integer string.
- `referral_profit_usd` (string): Referral earned by this account, in micro-USD, as an integer string.
- `referral_profit_native` (string | null): Same as `referral_profit_usd`, in lamports or wei, as an integer string.
- `referral_fee_rate_current` (integer): Rate this account earns on its referrals, in basis points — the value [Update a license](#update-a-license) writes. Do not recompute paid or net amounts with it.
- `referrer_license_key` (string | null): License key of the referrer.
- `referrer_username` (string | null): Username of the referrer.
- `referrer_account_id` (string | null): Account id of the referrer.
- `referred_license_keys` (array<string>): License keys this account referred.
- `referred_count` (integer): Number of accounts referred.
- `referred_revenue_usd` (string): Fees paid by the accounts this one referred, in micro-USD, as an integer string.
- `referred_revenue_native` (string | null): Same as `referred_revenue_usd`, in lamports or wei, as an integer string.
- `referred_net_revenue_usd` (string): Referees' fees minus the referral paid back to this account, in micro-USD, as an integer string.

```json
{
  "account_id": "de6b26fc-9e5a-4a6b-9c50-0c75bc6c1598",
  "username": "demouser",
  "display_name": "Demo User",
  "avatar_url": null,
  "license_key": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
  "created_at": 1748196000,
  "tier": "standard",
  "fee_rate": 500,
  "sell_fee_rate": 500,
  "buy_fee_rate": 0,
  "cashback_rate": 0,
  "is_active": true,
  "is_internal": false,
  "launch_count": 42,
  "pnl_usd": "18250000000",
  "pnl_native": "96400000000",
  "volume_sold_usd": "412000000000",
  "volume_sold_native": "2210000000000",
  "volume_bought_usd": "393750000000",
  "volume_bought_native": "2113600000000",
  "fees_paid_usd": "20600000000",
  "fees_paid_native": "110500000000",
  "referral_paid_usd": "3090000000",
  "referral_paid_native": "16575000000",
  "referral_profit_usd": "1200000000",
  "referral_profit_native": "6400000000",
  "referral_fee_rate_current": 1500,
  "referrer_license_key": "AFFILIATE01-Qm4Tz8Lp2Xc7Vb9Nw",
  "referrer_username": "affiliate01",
  "referrer_account_id": "3d6201aa-c053-4969-af46-2ba4b92d54ac",
  "referred_license_keys": [
    "SAMPLEDEV-Hy6Rk1Ws9Jd3Fq8Lp"
  ],
  "referred_count": 1,
  "referred_revenue_usd": "8000000000",
  "referred_revenue_native": "42800000000",
  "referred_net_revenue_usd": "6800000000"
}
```

### List users

`GET /admin/users`

Returns a page of accounts with their fees, metrics and referral data. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Backs the admin users table. The account modal reads a single account with `account_id` and `limit=1`, the referred-accounts view lists up to 500 accounts by `referrer_account_id`, and the referrer picker searches by `search`.

#### Query parameters

- `limit` (integer, optional, default "100"): Page size. The API defaults to 100 and caps at 500.
- `offset` (integer, optional, default "0"): Number of rows to skip.
- `search` (string, optional): Matches part of the username or license key.
- `account_id` (string, optional): Restricts the results to one account.
- `referrer_account_id` (string, optional): Restricts the results to the accounts this account referred.
- `chain_id` (enum, optional): Restricts metrics to one chain. `all` is not sent. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `order_by` (enum, optional, default "created_at"): Sort column. The API refuses `sell_fee_rate`, `buy_fee_rate` and `cashback_rate`. Possible values: `created_at`, `username`, `license_key`, `launch_count`, `pnl_usd`, `pnl_native`, `volume_sold_usd`, `volume_sold_native`, `volume_bought_usd`, `volume_bought_native`, `fees_paid_usd`, `fees_paid_native`, `referral_paid_usd`, `referral_paid_native`, `referral_profit_usd`, `referral_profit_native`, `referral_rate`, `referred_count`, `referred_revenue_usd`, `referred_revenue_native`, `referred_net_revenue_usd`, `display_name`, `referrer_license_key`, `tier`, `fee_rate`, `sell_fee_rate`, `buy_fee_rate`, `cashback_rate`.
- `order` (enum, optional, default "desc"): Sort direction. Possible values: `asc`, `desc`.

#### Returns 200 OK

- `users` (array<object>): Accounts on this page. See [Admin user](#object-admin-user).
- `total` (integer): Total number of matching accounts.
- `limit` (integer): Applied page size.
- `offset` (integer): Applied offset.
- `native_mixed` (boolean): `true` when the results span several chains, so native amounts are not in a single unit.
- `units` (object): Unit labels for the amounts in the response.
  - `usd` (string): Unit of the USD amounts.
  - `native` (string): Unit of the native amounts.
  - `time` (string): Unit of the timestamps.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid order_by: <order_by>` | `order_by` is not a sortable column. The API refuses `sell_fee_rate`, `buy_fee_rate` and `cashback_rate`. An `order` other than `asc` or `desc` answers `invalid order: <order>`. | Sort on another `order_by` column, with `order` set to `asc` or `desc`. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/users" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "users": [
    {
      "account_id": "de6b26fc-9e5a-4a6b-9c50-0c75bc6c1598",
      "username": "demouser",
      "display_name": "Demo User",
      "avatar_url": null,
      "license_key": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
      "created_at": 1748196000,
      "tier": "standard",
      "fee_rate": 500,
      "sell_fee_rate": 500,
      "buy_fee_rate": 0,
      "cashback_rate": 0,
      "is_active": true,
      "is_internal": false,
      "launch_count": 42,
      "pnl_usd": "18250000000",
      "pnl_native": "96400000000",
      "volume_sold_usd": "412000000000",
      "volume_sold_native": "2210000000000",
      "volume_bought_usd": "393750000000",
      "volume_bought_native": "2113600000000",
      "fees_paid_usd": "20600000000",
      "fees_paid_native": "110500000000",
      "referral_paid_usd": "3090000000",
      "referral_paid_native": "16575000000",
      "referral_profit_usd": "1200000000",
      "referral_profit_native": "6400000000",
      "referral_fee_rate_current": 1500,
      "referrer_license_key": "AFFILIATE01-Qm4Tz8Lp2Xc7Vb9Nw",
      "referrer_username": "affiliate01",
      "referrer_account_id": "3d6201aa-c053-4969-af46-2ba4b92d54ac",
      "referred_license_keys": [
        "SAMPLEDEV-Hy6Rk1Ws9Jd3Fq8Lp"
      ],
      "referred_count": 1,
      "referred_revenue_usd": "8000000000",
      "referred_revenue_native": "42800000000",
      "referred_net_revenue_usd": "6800000000"
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0,
  "native_mixed": true,
  "units": {
    "usd": "micro_usd",
    "native": "lamports",
    "time": "unix_seconds"
  }
}
```

### List licenses with launches

`GET /admin/get-mints`

Returns every license with its launches and revenue figures. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Loaded on the legacy `/admin/v1` pages only, where the users and launches tables are built from it client-side.

#### Returns 200 OK

Returns an array with one entry per license.

- `license` (object): The license, in the shape its owner reads from `GET /license/get-license-info`, with its key under `license_key` and admin-only fields added.
  - `license_key` (string): License key.
  - `username` (string | null): Username.
  - `account_id` (string): Stable account id.
  - `tier` (string): License tier.
  - `fee_rate` (integer): Sell fee, in basis points.
  - `buy_fee_rate` (integer): Buy fee, in basis points.
  - `cashback_rate` (integer): Cashback rate, in basis points.
  - `is_active` (boolean): Whether the key is active.
  - `created_at` (string): Creation time.
  - `total_pnl_usd` (string): Lifetime P&L, in micro-USD, as an integer string.
  - `gross_volume_usd` (string): Lifetime gross volume, in micro-USD, as an integer string.
  - `referral` (object): Referral position: `referral_fee_rate`, `referred_keys`, `referrer_key`, `referrer_username`, `referrer_account_id`, profits and codes.
- `mints` (array<object>): The license's launches, in the shape of `GET /license/get-mints-info`, plus admin revenue fields.
  - `launch_id` (integer): Launch id.
  - `chain_id` (string): Proxima chain id.
  - `mint_pubkey` (string | null): Token address.
  - `launch_platform` (string): Launchpad.
  - `launch_method` (enum): Launch method. Possible values: `Mev`, `Stagger`, `Manual`, `Allowlist`.
  - `launch_status` (string): Launch status.
  - `holder_count` (integer | null): Token holder count.
  - `gross_revenue_usd` (string): Fees Proxima earned on the launch, in micro-USD, as an integer string.
  - `gross_revenue_native` (string): Same, in lamports or wei, as an integer string.
  - `referral_paid_usd` (string): Referral paid on the launch, in micro-USD, as an integer string.
  - `referral_unpaid_usd` (string): Referral still owed on the launch, in micro-USD, as an integer string.
  - `referral_unpaid_status` (enum): `settling` while a queued sweep will still pay the unpaid referral. Possible values: `settled`, `settling`, `requires_reconciliation`.
  - `revenue_net_usd` (string): Revenue after referral, in micro-USD, as an integer string.
- `launch_count` (integer): Number of launches.
- `referred_revenue_usd` (string): Fees paid by the licenses this one referred, in micro-USD, as an integer string.
- `referred_net_revenue_usd` (string): Referees' fees minus the referral paid back to this license, in micro-USD, as an integer string.

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/get-mints" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
[
  {
    "license": {
      "license_key": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
      "username": "demouser",
      "account_id": "de6b26fc-9e5a-4a6b-9c50-0c75bc6c1598",
      "tier": "standard",
      "fee_rate": 500,
      "buy_fee_rate": 0,
      "cashback_rate": 0,
      "is_active": true,
      "created_at": "2026-05-25T18:00:00",
      "total_pnl_usd": "18250000000",
      "gross_volume_usd": "805750000000",
      "referral": {
        "is_referred": true,
        "referral_fee_rate": 1500,
        "referred_keys": [
          "SAMPLEDEV-Hy6Rk1Ws9Jd3Fq8Lp"
        ],
        "referrer_key": "AFFILIATE01-Qm4Tz8Lp2Xc7Vb9Nw",
        "referrer_username": "affiliate01",
        "referrer_account_id": "3d6201aa-c053-4969-af46-2ba4b92d54ac"
      }
    },
    "mints": [
      {
        "launch_id": 18234,
        "chain_id": "sol",
        "mint_pubkey": "Pp3T3fAScMGZUxEMhYc34Bju7BTD5kF1z36adQsuMjdF",
        "launch_platform": "pumpfun",
        "launch_method": "Mev",
        "launch_status": "Finalized",
        "holder_count": 211,
        "gross_revenue_usd": "412000000",
        "gross_revenue_native": "2210000000",
        "referral_paid_usd": "61800000",
        "referral_unpaid_usd": "0",
        "referral_unpaid_status": "settled",
        "revenue_net_usd": "350200000"
      }
    ],
    "launch_count": 42,
    "referred_revenue_usd": "8000000000",
    "referred_net_revenue_usd": "6800000000"
  }
]
```

### Create a license

`POST /admin/add-license`

Creates an account with a new license key. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. A lost call may have created the account, and a repeat then fails with `username already exists`. Search for the username with [List users](/reference/admin-users/#list-users) to read its key.

The admin form strips the username to letters and digits and enters rates as percentages, sent in basis points. No referral code is consumed. The key is the upper-cased username, a hyphen and 17 random alphanumeric characters.

> The response is the only place the new key is returned; hand it to the account owner securely.

> The API currently ignores `referrer`, `referral_fee_rate` and `fee_rate`: the account starts with no referrer and default rates. Set them afterwards with [Update a license](#update-a-license).

#### Body parameters

- `username` (string, required): Username of the new account: 3–50 letters, digits or hyphens, starting and ending with a letter or digit.
- `referrer` (string, optional): Username of the referrer.
- `referral_fee_rate` (integer, optional): Rate the new account earns on its own referrals, in basis points.
- `fee_rate` (integer, optional): Sell fee, in basis points.

#### Returns 200 OK

- `license_key` (string): The new license key.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `username must be 3-50 chars` | The username is not 3–50 characters. Other format messages: `username must start and end with a letter or number`, `username must be letters, numbers, or hyphens`. | Send a username of 3 to 50 letters, digits or inner hyphens. |
| 400 | `bad_request` | `username already exists` | Another account already has this username. | Choose another username, or find the existing account with [List users](/reference/admin-users/#list-users). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/add-license" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "newtrader",
  "referrer": "affiliate01",
  "referral_fee_rate": 1500,
  "fee_rate": 500
}'
```

#### Example response

```json
{
  "license_key": "NEWTRADER-Zt7Qp2Lm9Xc4Vb8Nk"
}
```

### Update a license

`POST /admin/update-license`

Changes an account's referrer, referral rate, fees or cashback rate. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Only the fields present are written, so a repeat sets the same values.

Only the fields present change. The client sends `new_referrer_account_id` when the referrer was picked from the user list and `new_referrer` (a username) otherwise, never both; an empty `new_referrer` clears the referrer. Rates are basis points from 0 to 10000 and also accept decimal strings. Changing the referrer does not waive referral already accrued.

> The API currently ignores `new_cashback_rate`.

#### Body parameters

- `account_id` (string, required): Target account id (see [Admin user](#object-admin-user)).
- `new_referrer` (string, optional): Referrer's username. Empty string clears the referrer.
- `new_referrer_account_id` (string, optional): Referrer's account id. Takes precedence over `new_referrer` in the client.
- `new_referral_fee_rate` (integer, optional): Rate this account earns on its referrals, in basis points.
- `new_fee_rate` (integer, optional): Sell fee, in basis points.
- `new_buy_fee_rate` (integer, optional): Buy fee, in basis points.
- `new_cashback_rate` (integer, optional): Share of what Proxima keeps on this account's launches, after referrals, paid back to it, in basis points.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `account_id, license_key or username is required` | No target account is given. | Send the target's `account_id`. |
| 404 | `not_found` | `License not found` | No account has this `account_id`. | Take the `account_id` from [List users](/reference/admin-users/#list-users). |
| 404 | `not_found` | `Referrer account not found` | `new_referrer_account_id` matches no account. An unknown `new_referrer` username answers `Referrer username not found`. | Pick the referrer from [List users](/reference/admin-users/#list-users). |
| 400 | `bad_request` | `Invalid new fee rate` | `new_fee_rate` is above 10000. The other rates answer `Invalid new referral fee rate` and `Invalid new buy fee rate`. | Send rates in basis points, from 0 to 10000. |
| 400 | `bad_request` | `that referrer would create a referral cycle` | The new referrer is the account itself or one of its own referrals. | Choose a referrer outside the account's own referral tree. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/update-license" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "de6b26fc-9e5a-4a6b-9c50-0c75bc6c1598",
  "new_referrer_account_id": "3d6201aa-c053-4969-af46-2ba4b92d54ac",
  "new_fee_rate": 400,
  "new_cashback_rate": 1000
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully updated license key"
}
```

### Rotate a license key

`POST /admin/rotate-key`

Replaces an account's license key with a new one. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. Each call issues another key. Compare the account's `license_key` in [List users](/reference/admin-users/#list-users) (filtered by `account_id`) with the key you had before retrying.

The license keeps its data under the new key. Started from the account modal after a confirmation.

> Irreversible: the previous key stops existing. Give the owner the new key.

#### Body parameters

- `account_id` (string, required): Target account id (see [Admin user](#object-admin-user)).

#### Returns 200 OK

- `new_key` (string): The new license key.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `account_id or username is required` | `account_id` is missing. | Send the target's `account_id`. |
| 400 | `bad_request` | `Cannot rotate your own key` | The key belongs to the calling admin's own user. | Have another admin rotate this key. |
| 404 | `not_found` | `account not found` | No account has this `account_id`. | Take the `account_id` from [List users](/reference/admin-users/#list-users). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/rotate-key" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "de6b26fc-9e5a-4a6b-9c50-0c75bc6c1598"
}'
```

#### Example response

```json
{
  "new_key": "DEMOUSER-Rw5Hn2Jc8Lq4Zt7Xm"
}
```

### Activate or deactivate a license key

`POST /admin/set-key-active`

Turns an account's license key on or off. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. The call sets a state, so a repeat changes nothing.

#### Body parameters

- `account_id` (string, required): Target account id (see [Admin user](#object-admin-user)).
- `is_active` (boolean, required): `false` deactivates the key, `true` reactivates it.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `account_id or username is required` | `account_id` is missing. | Send the target's `account_id`. |
| 400 | `bad_request` | `Cannot deactivate your own key` | Deactivating a key that belongs to the calling admin's own user. | Have another admin deactivate this key. |
| 404 | `not_found` | `account not found` | No account has this `account_id`. | Take the `account_id` from [List users](/reference/admin-users/#list-users). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/set-key-active" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "de6b26fc-9e5a-4a6b-9c50-0c75bc6c1598",
  "is_active": false
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "License key deactivated"
}
```

### List an account's licenses

`GET /admin/users/licenses`

Returns every license owned by the user behind an account. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Shown in the *Licenses* tab of the update-account modal.

#### Query parameters

- `account_id` (string, required): Account id of any license the user owns.

#### Returns 200 OK

- `user_id` (string): Id of the owning user.
- `licenses` (array<object>): Licenses the user owns.
  - `key` (string): License key.
  - `account_id` (string): Account id.
  - `username` (string): Username.
  - `display_name` (string | null): Display name.
  - `tier` (string): License tier.
  - `is_active` (boolean): Whether the key is active.
  - `avatar_url` (string | null): Avatar URL.
  - `banner_url` (string | null): Banner URL.
  - `banner_theme` (string | null): Banner preset id.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `username or account_id is required` | `account_id` is missing. | Send `account_id`. |
| 404 | `not_found` | `account not found` | No account has this `account_id`. | Take the `account_id` from [List users](/reference/admin-users/#list-users). |
| 409 | `conflict` | `target account has no associated user` | The account is not attached to a user, so there is no license list to read. | Read the account on its own with [List users](/reference/admin-users/#list-users). |

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/users/licenses?account_id=%3Caccount_id%3E" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "user_id": "30ef31c8-0d62-4ba0-ab8a-04056428b5c5",
  "licenses": [
    {
      "key": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
      "account_id": "de6b26fc-9e5a-4a6b-9c50-0c75bc6c1598",
      "username": "demouser",
      "display_name": "Demo User",
      "tier": "standard",
      "is_active": true,
      "avatar_url": null,
      "banner_url": null,
      "banner_theme": null
    }
  ]
}
```

### Create a read token

`POST /admin/tokens/read`

Issues a read-only JWT for tools, bound to its own session. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. Each call opens another session, and a lost token cannot be shown again. Find the session with user agent `read-token: <label>` in [List sessions](/reference/authentication/#list-sessions) and end it with [Revoke a session](/reference/authentication/#revoke-session).

The token carries the caller's user and current license but is refused on every method except `GET`. It gets a session of its own, listed under its label in *Settings → Sessions*, so revoking it there leaves the admin signed in. The admin *Tokens* page creates it.

> The token is shown only in this response. Store it like a password and revoke its session when it is no longer needed.

#### Body parameters

- `ttl_seconds` (integer, optional, default "7776000"): Lifetime, in seconds, from 60 to 15552000 (180 days). Also accepts a numeric string.
- `label` (string, optional): Name shown in the session list, up to 60 characters. Trimmed.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `token` (string): The read-only JWT. Send it as `Authorization: Bearer <token>`.
- `session_id` (string): Session the token belongs to.
- `expires_in` (integer): Lifetime applied, in seconds.
- `expires_at` (integer): Expiry, Unix seconds.
- `label` (string | null): Label applied.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `upgrade onto a license before minting a read token` | The caller's session has not been upgraded onto a license yet. | Upgrade the session with [Upgrade a session token](/reference/authentication/#upgrade-token) first. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/tokens/read" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "ttl_seconds": 2592000,
  "label": "Metrics notebook"
}'
```

#### Example response

```json
{
  "ok": true,
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJleGFtcGxlIjp0cnVlfQ.c2lnbmF0dXJlLW5vdC1yZWFs",
  "session_id": "ad1db068-74c6-4ff0-966f-82d2ee372b0d",
  "expires_in": 2592000,
  "expires_at": 1796173200,
  "label": "Metrics notebook"
}
```
