Key scopes
Limit a key to certain customers, models or providers, checked at the gateway before every request.
A scope limits what a CoreValue key can be used for. Scopes are checked at the gateway before rate limits and budgets, so a caller cannot widen a key's access by changing its request headers.
Scope a key
- Go to Governance → Keys and click Scopes on the key. This works for API keys and virtual keys alike.
- Add entries to any of Customers, Models and Providers. An empty field means Any. Customers are suggested from this month's traffic.
- Click Save. Clear all scopes removes every limit.
Each field takes up to 100 entries. Customer IDs are matched without regard to case.
What a scoped key does
| Scope | Request | Result |
|---|---|---|
| Customers: exactly one | No Cova-Customer-Id | Counted for that customer, including against its budget. |
| Customers: several | No Cova-Customer-Id | Refused, 400 customer_header_required: the key must say which customer. |
| Customers: any number | A customer not in the list | Refused, 403 customer_not_allowed. |
| Models | A model not in the list | Refused, 403 model_not_allowed. |
| Providers | A provider not in the list | Refused, 403 provider_not_allowed. |
Refusals use the error format of the API you called (permission_error or
invalid_request_error; PERMISSION_DENIED or INVALID_ARGUMENT for Google),
and are recorded in the request log at $0.
Good practice
Give each application, environment and, if you resell AI, each customer its own key. A key scoped to one customer binds every request to that customer without any header; see Per-customer budgets.
Changing scopes needs the keys.write permission.