diff --git a/v3/general/custom-api-keys.mdx b/v3/general/custom-api-keys.mdx index f6e0296..2b1fbd0 100644 --- a/v3/general/custom-api-keys.mdx +++ b/v3/general/custom-api-keys.mdx @@ -14,7 +14,7 @@ import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; proficiencyLevel="Intermediate" keywords={["Eden AI", "AI API", "rate limits", "billing", "monitoring"]} datePublished="2026-05-06T00:00:00Z" - dateModified="2026-05-07T00:00:00Z" + dateModified="2026-07-21T00:00:00Z" /> Custom API keys let you create additional tokens beyond your main account key. Each token can have its own budget, expiration, and type, giving you fine-grained control over access and spending. @@ -122,6 +122,66 @@ curl -X POST https://api.edenai.run/v2/user/custom_token/ \ When `active_balance` is `true`, every API call deducts from the token's balance. Once it reaches $0, the token stops working. +## Periodic Budget Reset + +A budget can either **reinitialize automatically** each day, week, or month, or be a **one-time** allowance that stays at $0 once spent until you top it up manually. You control this with `balance_reset_period` (the reset frequency) and `balance_reset_amount` (the amount the balance is restored to at the start of each period). + +### In the dashboard + +On the [API Keys](https://app.edenai.run/settings/api-keys) page, create or edit a key and turn on **Spending Limit**. Set the **Reset allowance** (the amount restored each period) and choose a **Resets** frequency — **Daily**, **Weekly**, **Monthly**, or **Never**. A reset frequency is always selected when a spending limit is on; it defaults to **Monthly**. Choose **Never** for a one-time budget that does not renew. A separate **Current balance** field shows what's available right now; editing the allowance only takes effect at the next reset. + +### Through the API + + +```python Python +import requests + +headers = { + "Authorization": "Bearer YOUR_API_KEY", + "Content-Type": "application/json" +} + +response = requests.post( + "https://api.edenai.run/v2/user/custom_token/", + headers=headers, + json={ + "name": "team-daily", + "token_type": "api_token", + "balance_reset_amount": "10.00", + "balance_reset_period": "daily" + } +) +``` + +```bash cURL +curl -X POST https://api.edenai.run/v2/user/custom_token/ \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "team-daily", + "balance_reset_amount": "10.00", + "balance_reset_period": "daily" + }' +``` + + +| Field | Values | Meaning | +|-------|--------|---------| +| `balance_reset_period` | `none`, `daily`, `weekly`, `monthly` | How often the balance is restored. `none` = one-time budget; it is the default when the field is omitted from the API request. (The dashboard instead pre-selects **Monthly** when you enable a spending limit.) | +| `balance_reset_amount` | positive amount | The value the balance is reset to each period. Required whenever the period is not `none`. | + +Behaviour to know: + +- Setting a reset period **automatically enforces the budget** (`active_balance` becomes `true`) — you don't have to set it separately. +- `balance_reset_amount` is the reset **target**, kept separate from the live `balance` (the amount remaining right now). They are not the same field. +- A new periodic token **starts the period full**: if you don't pass a starting `balance`, it begins at `balance_reset_amount`. Passing an explicit `balance` lets a key start partway through a period. +- Resets run at **midnight Europe/Paris time**: daily every night, weekly on Monday, monthly on the 1st. +- Setting the period back to `none` clears `balance_reset_amount` and returns the token to a one-time budget. + + +This per-token reset is distinct from the **per-member budget cap** you can set on a [guardrail](/v3/organization/guardrails#budget-cap). A token budget is a hard cap on one key (it stops at $0); a member budget is a soft periodic spend cap that follows a person across all their keys. + + ## List All Tokens @@ -155,6 +215,7 @@ Use clear naming conventions like `env-project-purpose` (e.g., `prod-billing-api - **Set budgets on non-production tokens** to prevent accidental overspending during development. +- **Use a periodic reset** (`balance_reset_period`) for recurring allowances — e.g. a $10/day CI key — instead of topping up manually. - **Use sandbox tokens for CI/CD** to validate integrations without incurring costs. - **Rotate tokens periodically** — create a new token, migrate your application, then delete the old one. - **Set expiration dates** on temporary tokens (e.g., for contractors or short-term projects). diff --git a/v3/organization/guardrails.mdx b/v3/organization/guardrails.mdx index 53cb67e..0f0be5d 100644 --- a/v3/organization/guardrails.mdx +++ b/v3/organization/guardrails.mdx @@ -1,28 +1,29 @@ --- icon: "shield-check" title: "Guardrails" -description: "Guardrails are reusable usage policies that control which models your team can call and how often. Create them in the dashboard and attach them to roles, members, or API tokens." +description: "Guardrails are reusable usage policies that control which models your team can call, how often, and how much a member can spend. Create them in the dashboard and attach them to roles, members, or API tokens." --- import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; -A **guardrail** is a reusable usage policy that controls two things: +A **guardrail** is a reusable usage policy that controls: - **Model access**: which providers and models can be called. - **Rate limits**: how many requests can be made over a given period. +- **Member budget**: a spending cap for a member over a period (see [Budget cap](#budget-cap)). -You create a guardrail once, then attach it to a **role**, a **member**, or an individual **API token**. For example, one team can be limited to a curated set of models, or a shared token can be capped to a low request rate. +You create a guardrail once, then attach it to a **role**, a **member**, or an individual **API token**. For example, one team can be limited to a curated set of models, a shared token can be capped to a low request rate, or a member can be given a monthly spending cap. Guardrails are part of the advanced organisation features. See [plans and pricing](https://www.edenai.co/pricing) for availability. @@ -43,6 +44,9 @@ In the **Rate Limit** field, enter a limit in the form `N/period`, for example ` Turn on **Enable model rules** to control which models can be used, then define your allow/deny rules. See [Model rules](#model-rules) below. + +Enter a **Budget** amount and a **period** (daily, weekly, or monthly) to cap how much a member can spend. See [Budget cap](#budget-cap) below. + Click **Create Guardrail**. It now appears in your guardrails list, ready to assign. @@ -83,6 +87,28 @@ The rate limit uses the format `N/period`, where `period` is `second`, `minute`, Leave the rate limit empty on a guardrail to inherit it from the next level up (role → organisation default). +## Budget cap + +A guardrail can cap how much a **member** spends over a recurring period. In the **Create/Edit Guardrail** dialog, turn on **Member budget** ("Cap each member's spend across all their API keys"), then set a **Budget** amount (in USD) and a **Per** period: + +| Period | Window | +| --- | --- | +| `daily` | Resets each day | +| `weekly` | Resets each week | +| `monthly` | Resets each month | + +Both fields are set together — a budget needs a period, and a period needs an amount. Leave them empty to apply no spend cap. + +How it behaves: + +- **Per member, not shared.** The cap applies to each member the guardrail resolves to individually — it is not a shared pool across the team. +- **Soft cap.** The check happens before each request. A request already in flight can push spend past the cap; the *next* request is the one that gets blocked. The limit is a spending guardrail, not a hard cutoff mid-request. +- **Counts real usage only.** [Sandbox](/v3/general/sandbox) calls and calls made with your own provider keys ([BYOK](/v3/general/byok)) don't count toward the budget. Refunds credit it back. + + +The budget only applies when a guardrail is attached to a **role** or a **member**. A budget set on a guardrail that is attached to an **API token** is ignored — use a [token budget](/v3/general/custom-api-keys) to cap a single key instead. + + ## Assigning a guardrail A guardrail does nothing until it's attached to something. You can assign it to: @@ -97,7 +123,9 @@ When a request comes in, Eden AI resolves the policy **per field, most specific token → member → role → organisation default ``` -For each setting (model rules and rate limit) independently, Eden AI uses the value from the most specific level that has it set, and inherits the rest. So a token can override the model rules while still inheriting its role's rate limit. +For **model rules** and **rate limit** independently, Eden AI uses the value from the most specific level that has it set, and inherits the rest. So a token can override the model rules while still inheriting its role's rate limit. + +The **member budget** resolves differently: only the **member** and **role** levels are considered (token budgets are handled separately, on the token itself), and the budget amount and period are always taken together from the most specific level that sets them — they are never mixed across levels. Guardrails can also be managed programmatically through the User Management API if you need to automate provisioning. See the [API Reference](https://www.edenai.co/docs) for the `guardrails` endpoints. @@ -106,5 +134,5 @@ Guardrails can also be managed programmatically through the User Management API ## Related - [Users & Organisation](/v3/organization/users-organisation): roles, permissions, and members. -- [Custom API Keys](/v3/general/custom-api-keys): per-token budgets that pair well with per-token guardrails. +- [Custom API Keys](/v3/general/custom-api-keys): per-token budgets, which cap a single key rather than a member. - [Rate Limits](/v3/overview/rate-limits): how default rate limiting works. diff --git a/v3/organization/users-organisation.mdx b/v3/organization/users-organisation.mdx index dbca7a9..18d1491 100644 --- a/v3/organization/users-organisation.mdx +++ b/v3/organization/users-organisation.mdx @@ -14,7 +14,7 @@ import { TechArticleSchema } from "/snippets/TechArticleSchema.mdx"; proficiencyLevel="Intermediate" keywords={["Eden AI", "AI API", "RBAC", "roles", "permissions", "organisation"]} datePublished="2026-06-11T00:00:00Z" - dateModified="2026-06-11T00:00:00Z" + dateModified="2026-07-21T00:00:00Z" /> Eden AI provides team and organisation management features for companies that need structured access control, role-based permissions, and governance over their AI usage. @@ -62,7 +62,7 @@ If the built-in roles don't fit, click **+ Create Role** to define a custom role ## Guardrails -Beyond who can manage the organisation, you can control **which models members can call and how often** using [guardrails](/v3/organization/guardrails): reusable usage policies that combine model/provider access rules with rate limits. Guardrails can be attached to a role, an individual member, or a single API token, and resolve most-specific-first (token → member → role → organisation default). +Beyond who can manage the organisation, you can control **which models members can call, how often, and how much they can spend** using [guardrails](/v3/organization/guardrails): reusable usage policies that combine model/provider access rules, rate limits, and per-member budget caps. Guardrails can be attached to a role, an individual member, or a single API token. Model rules and rate limits resolve most-specific-first (token → member → role → organisation default); the per-member budget cap resolves at the member and role levels only (budgets set on a token-attached guardrail are ignored). ## Single Sign-On & Directory Sync