Quota grants

A quota grant raises an owner’s quota rules above what their quota groups allow. Grants are written by an integration, an external system that talks to Arbinel with a token of its own. Use them when something outside Arbinel decides who gets more quota, such as your own billing system, a sponsorship programme or a support tool. Read Quotas first.

Grants and groups

Quota groups do not add up. Across groups the most generous rule wins, so an owner in a 10 GiB group and a 5 GiB group has 10 GiB, not 15 GiB. To give one owner 5 GiB more with groups alone, you have to create a group per owner and recompute it whenever the base changes.

Grants add up. The integration only writes the extra amount, and you can change the groups without changing the grants.

Enable grants

[quota.grants]
ENABLED = true

[integration.billing]
TOKEN_HASH = 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
SCOPES = quota.grants

Key	Default	Meaning
[quota.grants] ENABLED	false	Turns grants on. While it is off, stored grants raise nothing and the grant routes do not exist.
[integration.<name>]	none	One section per integration. The section name is the integration’s name: lower-case letters, digits, - and _, up to 40 characters.
TOKEN_HASH	none	The hex SHA-256 of the integration’s token. Create it with printf %s "$TOKEN" | sha256sum. Only the hash goes in app.ini.
SCOPES	none	What the integration may do, comma separated. quota.grants is the only scope so far.

Arbinel ignores an integration section with an invalid name, a malformed hash, or a hash another integration already uses, and logs an error. It drops scopes it does not know and keeps the rest. The integration API at /api/v1/integrations only exists while at least one integration is configured.

How a grant raises a quota

A grant has a list of subjects and an amount. It adds the amount to every rule of the owner that names one of the subjects.

• A rule that names several of the subjects is raised once.
• The amount is in the rule’s unit: bytes for size: and egress:all, seconds for time: subjects.
• An amount of -1 lifts the rules to unlimited.
• A rule that is already unlimited stays unlimited.
• Grants from several integrations, and paid add-ons, all add up.

A grant only raises rules that exist.

• It matches subjects exactly. A grant on size:git:lfs does not raise a rule on size:all.
• An owner in no quota group has no rule to raise, and the [quota.default] and [quota.ci.default] fallbacks are never raised.

API

The integration sends Authorization: Bearer <token> with every request. A wrong token gets 401, and an integration without the quota.grants scope gets 403. Each integration only sees and replaces its own grants.

Replace an owner’s grants

PUT /api/v1/integrations/quota/grants/{owner_id}
Content-Type: application/json

{
  "grants": [
    {"ref": "plan-pro", "subjects": ["size:all"], "amount": 21474836480},
    {"ref": "promo-ci", "subjects": ["time:ci:all"], "amount": 36000, "expires_at": "2026-12-31T23:59:59Z"}
  ]
}

owner_id is the numeric ID of the user or organization, as GET /api/v1/users/{username} or GET /api/v1/orgs/{org} returns it.

The grants you send become the only ones this integration keeps for the owner, in one step.

• An empty grants list removes them all.
• Sending the same set again changes nothing, so the integration can resend its full state on every change or on a schedule.
• Other integrations’ grants for the owner stay as they are.

Field	Meaning
ref	The integration’s own name for the grant, unique per owner, 1 to 191 printable characters.
subjects	One or more quota subjects. Arbinel refuses an unknown subject with 422.
amount	A positive number in the rules’ unit, or -1 for unlimited.
expires_at	Optional. After this time the grant raises nothing, but it is still listed.

An integration can keep at most 100 grants per owner. An unknown owner gets 404.

List grants

GET /api/v1/integrations/quota/grants?owner_id=42&page=1&limit=50

This lists the integration’s grants, expired ones included, ordered by owner and ref. Leave out owner_id to list every owner’s grants. The response is paginated like the rest of the API.

Grants in the owner’s settings

A grant raises the limit the owner sees on their Storage overview, CI/CD usage and Add-ons pages. These pages do not list grants separately. On the Add-ons page, grants count towards the Included column.