🚀 feat: Admin balance management API endpoints

[olivierbossel]

🚀 feat: Admin balance management API endpoints

Manage balances through some API-Key protected API endpoints:

Related pull request: #11698

• GET /api/balance/admin/get-balance
• POST /api/balance/admin/set-balance
• POST /api/balance/admin/add-balance

GET /api/balance/admin/get-balance

Get the balance for a specific user.

Query params:

• email: The user email wanted

JSON response:

{
    "email": "...",
    "balance": 1009,
    "perSpecTokenCredits": {
        "buzz-gpt-4-1": 1009
    }
}

POST /api/balance/admin/set-balance

Set the balance of a specific user:

JSON payload:

{
    "email": "...",
    "amount": 1000,
    # Optional spec (see related pull request)
    # "spec": "Buzz GPT-4.1"
}

JSON response:

{
    "message": "Balance set successfully to 1000 for user ... and spec ...",
    "email": "...",
    "balance": 1009,
    "perSpecTokenCredits": {
        "buzz-gpt-4-1": 1000
    }
}

POST /api/balance/admin/add-balance

Add some credits to a specific user.

JSON payload

{
    "email": "ob@buzzbrothers.ch",
    "amount": 9,
    # Optional spec (see related pull request)
    # "spec": "Buzz GPT-4.1"
}

### JSON response

{
    "message": "9 added successfully for user ... and spec ...",
    "email": "...",
    "balance": 1009,
    "perSpecTokenCredits": {
        "buzz-gpt-4-1": 1009
    }
}

API Key authentication

To access these endpoints, you need to configure some api-key(s) to your installation in your librechat.yml file like so:

# Admin access configuration for securing admin endpoints with API keys
# These access are required to execute admin operations such as:
# - Managing balances
# - Others to come...
adminAccess:
  - apiKey: "librechat-admin-api-key-1234567890"
    name: "Main admin key"
    description: "Admin API Key with full access permissions"

You will then add the x-api-key header to your requests in order to be authorized to execute these actions.

Change Type

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Checklist

Please delete any irrelevant options.

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in any complex areas of my code
• I have made pertinent documentation changes
• My changes do not introduce new warnings
• Local unit tests pass with my changes

@todo

If this pull request is accepted, I will make the documentation update accordingly.