Access Profiles

​

Overview

• Reusable policy - Define a profile once (for example, “Engineering”) and apply it to every user in a role, or to a whole team, business unit, or customer.
• Per-user enforcement - Each user gets an independent copy with isolated budget and rate-limit counters.
• Shared group budgets - Attached to a team, business unit, or customer, a profile becomes one shared budget for everyone under it, charged alongside each member’s own profile.
• Layered access - A user can hold several profiles at once. What they can reach adds up, and if one profile’s budget runs out another can cover their requests.
• Role auto-assignment - Attach profiles to a role and users gaining that role are provisioned automatically.
• Safe propagation - Edit the template, then push selected fields (budgets only, MCP only, and so on) to every user and group holding it in one call.
• Locked virtual keys - A key whose owner holds a profile is write-protected, so a user cannot weaken their own policy by editing the key directly.
• Govern user-created keys - Remove the Create Standalone permission from a role and every virtual key its members create is owned by them and governed by their profiles, not just the auto-issued key. Members who hold no profile still get keys with no profile governing them.
• Audit and versioning - Every change to a profile is recorded with a full snapshot history.

​

Where a profile can be applied

​

Profiles on users

​

How a user gets a profile

• Removing a role only removes the profiles that role granted. Profiles from other sources are untouched.
• If an admin assigned a profile by hand and an IdP mapping later grants the same one, the mapping takes it over. From then on it follows the IdP, and it is removed when the user stops matching the mapping.
• A profile granted by a mapping can’t be detached from the user directly. Change the mapping or the user’s attribute in your IdP.

​

What the user gets

1. User copy - Bifrost copies the profile to the user, with its own budget and rate-limit counters. Each user’s usage is tracked separately.
2. Virtual key - A user with no virtual key is issued one. A key is never attached to a profile directly: it belongs to the user, and is governed by every profile the user holds. That is why it keeps working as their profiles change.
3. Locked key - Only the name and description of a virtual key can be edited, so the policy can’t be worked around. To change what the key allows, edit the profile.

​

Profiles on teams, business units, and customers

​

What attaching does

1. Entity copy - Bifrost copies the profile to the entity once. Its budgets and rate limits form one shared pool, and every member’s requests count toward it.
2. Virtual keys - The entity’s keys stay owned by the entity. Because the entity now holds a profile, every key it owns is governed by that profile and locked: the profile’s providers, budgets, limits, and MCP access replace the key’s own.
3. Members - Members are covered from their next request, and stop being covered as soon as they leave. No copies are made for them and no keys are issued to them.

​

What members can access

• A user is covered by the profiles of every team and every business unit they belong to.
• A user is also covered by the profile of every customer those teams and business units belong to. A customer reached through both a team and a business unit counts once.

​

Multiple profiles: what a user can do and who pays

​

Rule 1: access adds up

​

Rule 2: one personal profile pays, and every group profile is charged

1. One of the user’s own profiles pays. Bifrost looks only at the user’s own profiles that allow the requested model and still have budget and rate limit left, then picks one. Only that profile’s budgets move. The user’s other personal profiles are not touched.
2. Every team, business unit, and customer profile the user answers to is charged. These are charged on every request the user makes, whichever profile allowed the model. A group profile’s provider budget is charged when it has a budget for the provider being used, and its per-model budget when it has one for that model.

​

Common scenarios

​

When a request is refused

Budget exceeded: team_access_profile Team Pool budget exceeded: 5000.1200 >= 5000.0000 dollars

​

Requests made with group-owned keys

• The key is governed by its owner’s profile, plus the profile of every customer above that owner.
• That profile is charged, and so is every customer profile above it.
• If the profile is detached and the keys are preserved, a key only reaches what a customer profile above its owner allows. With no customer profile above, it can’t reach any model.

​

Lifecycle

​

Virtual keys and profiles

​

Keys are locked when their owner holds a profile

​

Keys members create

• With Create Standalone, a user can create ordinary keys with any policy their other permissions allow.
• Without Create Standalone, every key they create is owned by them, so it is governed by their profiles and locked. A user who holds no access profile still gets a key, with no profile governing it. A team, business unit, or customer named on the new key is ignored, so naming a team can’t be used to escape their own limits.
• A key created under a team, business unit, or customer that has a profile (by a user free to create standalone keys) belongs to that entity only, so it is governed by the entity’s profile.

​

Governing an existing key with a profile

• For a user, assign the key to them from the key’s edit sheet. It is then governed by the profiles they hold.
• For a team, business unit, or customer, open the entity’s Virtual Keys tab and use Assign Existing. Bifrost confirms before the entity takes ownership of the key, and the key is unassigned from any user it was attached to, since a key can have only one owner.

​

Automatic virtual key rotation

• If client.vk_rotation_cooldown is set (Config → Security), the previous value keeps authenticating until the cooldown expires, so callers have time to pick up the new key.
• Leaving it unset, empty, or 0 disables the grace period, so the previous value stops working immediately.

• A key is never rotated twice for one scheduled run. Rotating again would push the previous value out and end the cooldown early. Retries, resumed jobs, catch-up runs after downtime, and keys rotated manually after the schedule fired are all skipped for that run.
• Manual rotation still works. The manual endpoints stay available on these keys; a key rotated manually inside the window is simply skipped by the scheduled run.
• Cluster-safe. Every node checks the schedule, but only one job is created per profile and due time, and rotated keys are gossiped to all nodes.
• Missed runs collapse into one. If the gateway was down past a due time, the next start performs a single catch-up rotation rather than one per missed period.
• Deactivated profiles pause. A deactivated profile is never rotated; reactivating it re-anchors an overdue schedule to now + interval so it does not fire immediately.

​

Configuration (Web UI)

​

Browse and create profiles

1. Navigate to Governance → Access Profiles.

2. Click Create Profile.

​

Fill in the basics

• Name - Required and unique. Max 255 characters.
• Description - Optional, shown in the list view.

​

Configure provider access

• Allowed Models - Toggle All Models, or pick specific models. An empty selection allows no models from that provider.
• Provider Budget - One or more budget lines, each with a max limit and a reset duration (1h, 1d, 1w, 1M, 1Q, 1Y). Stack lines with different durations, for example a hard hourly cap plus a softer monthly cap. A quarterly line can follow your fiscal quarters - see Quarterly budgets.
• Maximum Tokens / Maximum Requests - Per-provider rate limits.
• Per-model budgets - Optionally cap individual models under this provider. Each holder of the profile gets its own copy: one per user, or one shared copy per team, business unit, or customer.

​

Configure global budgets and rate limits

​

Align to the calendar

​

Schedule automatic key rotation

​

Configure MCP tool access

• Virtual MCPs - Grant existing Virtual MCPs.
• MCP Servers - Granting a server grants all of its tools.
• Individual Tool Overrides - Include or exclude specific tools.

​

Assign the profile to users

• To a role - From Governance → Roles & Permissions, open the role and click Attach Access Profile. Choose Set as default for new users and/or Apply to existing users with this role.
• To one user - Open the user from Governance → Users, go to the Access Profiles tab, and add it.
• From your identity provider - Add an access profile mapping in User Provisioning. See Access profile mappings.

​

Attach the profile to a team, business unit, or customer

1. Open Governance → Teams, Business Units, or Customers, and click the entity to open its detail sheet.
2. In the Access Profile field at the top of the sheet:
   • If it shows No access profile attached, click Attach, pick the profile, and confirm.
   • If it shows Uses legacy budgets and rate limits, click Migrate to access profile (see below).
3. Once attached, the field shows the profile with View access profile and Detach actions.

​

Migrate legacy budgets to a profile

• Choose which providers the profile allows: All providers, Specific providers, or none.
• Budgets with a matching reset window carry their current spend across, so nobody’s month restarts at zero.
• Anything that can’t carry across is listed before you confirm.

​

See what a user is charged

​

Propagate changes

​

Extend a budget for one user or one group

Effective limit = Base budget + Override amount

# Add or replace an override
curl -X PUT "$BIFROST_URL/api/users/$USER_ID/access-profiles/$PROFILE_ID/budgets/$BUDGET_ID/override" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "mode": "cycles", "cycles": 2}'

# Remove it
curl -X DELETE "$BIFROST_URL/api/users/$USER_ID/access-profiles/$PROFILE_ID/budgets/$BUDGET_ID/override" \
  -H "Authorization: Bearer $TOKEN"

​

Edit, duplicate, delete

• Edit - Opens the form in edit mode.
• Duplicate - Opens the form pre-filled from the original.
• Delete - Refused while any user, team, business unit, or customer still holds the profile.

​

Declaring profiles in config.json and Helm

{
	"access_profiles": [
		{
			"name": "Engineering",
			"provider_configs": [{ "provider_name": "openai", "all_models_allowed": true }],
			"budgets": [{ "id": "budget-engineering", "max_limit": 5000, "reset_duration": "1M" }]
		}
	],
	"governance": {
		"teams": [{ "id": "team-platform", "name": "Platform", "access_profile": "Engineering" }],
		"business_units": [{ "id": "bu-emea", "name": "EMEA", "access_profile": "Engineering" }],
		"customers": [{ "id": "customer-acme", "name": "Acme Corp", "access_profile": "Engineering" }]
	}
}

• Split mode (default) - The profile is attached when the entry is new or changes. Changes made in the dashboard are otherwise kept.
• config.json as source of truth - The file wins on every start. An entity entry without access_profile has its profile removed; its virtual keys are kept.

​

Examples

​

Give every engineer their own budget

1. Create an “Engineering” profile with the providers, models, and monthly budget each engineer should have.
2. Attach it to the Engineer role with Apply to existing users with this role and Set as default for new users.
3. Every engineer gets their own copy and a virtual key. New engineers are covered the moment they gain the role.

​

Cap a team’s total spend

1. Create a “Platform Pool” profile with a $5,000 monthly budget.
2. Open the Platform team and Attach Platform Pool.
3. Every request a Platform member makes, and every request made with a Platform-owned key, is charged to the one $5,000 pool. When it is spent, the team is paused until the next reset, even for members whose personal budgets have room.

​

Individual and team caps together

​

Bill a customer contract

​

Keep everyone’s keys on policy

​

Raise a monthly budget without resetting usage

1. Edit the profile and set the new monthly budget.
2. Click Save and Propagate, check only Budgets, and click Propagate.
3. Everyone holding the profile, including teams and customers, gets the new limit and keeps their month-to-date spend.

​

Next steps

• Teams, Business Units & Customers - How the organization hierarchy fits together and what each level is charged.
• Data Access Control - Control which teams, business units, and customers each operator can see.
• RBAC - Define the roles profiles attach to, and the Create Standalone permission.
• How Identity Sync Works - How profiles follow roles and IdP attributes.
• Projects - Scope access and spend to a piece of work rather than to a person.
• Virtual Keys - The underlying virtual key concept.
• Model Limits - Per-model limits outside of profiles.