Skip to main content

Roles

A role groups callers so DIAL Core can apply the same rules to all of them: which resources they may use, how many tokens and requests they may spend, how much money they may spend, and how they may share resources. A role name is a claim value from your identity provider, or a role assigned to an API key. This reference is for platform engineers who set access and usage limits; it assumes you know how DIAL Core is configured.

Access to a model, application, toolset, or route is granted with its userRoles field. A role entry adds limits and sharing rules on top. For the concepts, see Roles and rate limits.

Where roles are defined​

SourceLocation
Config fileroles.<name>
Configuration API/v1/roles/platform/<name>

DIAL Admin manages roles in Roles.

Fields​

FieldDescription
limitsToken and request limits per deployment. See Limits.
costLimitSpending limits in USD across all models. See Cost limits.
shareSharing limits per resource type. See Sharing limits.

When a role defines no limits for a deployment, the limits of the default role apply. When the default role defines none either, usage is unlimited.

Limits​

limits is a map keyed by deployment name.

FieldWindowDescription
minuteFloatingTokens per minute.
dayFixed calendarTokens per day.
weekFixed calendarTokens per week.
monthFixed calendarTokens per month.
requestHourFloatingRequests per hour.
requestDayFixed calendarRequests per day.
  • Floating windows (minute, requestHour) age usage out gradually as time passes, which spreads requests evenly.
  • Fixed calendar windows (day, week, month, requestDay) reset all at once at a boundary aligned to the calendar; "this month" runs from the first to the last day of the calendar month. Usage cannot exceed the limit until the next boundary, whenever in the period it accrued. The deployment-wide rateLimitSchedule sets the time zone, the first day of the week, and the reset time; without it, windows reset at 00:00 UTC, and weeks start on Monday.

GET /v1/deployments/{deployment_id}/limits, GET /v1/user/limits, and GET /v1/user/usage report the next boundary as resetsAt on each fixed-window entry. Floating-window entries have no resetsAt.

A request served through a translator is counted once, on the translator's callback.

Cost limits​

costLimit caps spending across all models, in USD, with minute, day, week, and month fields. Cost limits work alongside token and request limits, and use model pricing. The same default role fallback applies.

Callers who sign in through an identity provider can be governed by budgets instead, when spendingLimits.mode is enforce; callers with API keys always use costLimit. See Spending limits.

Sharing limits​

share is a map keyed by resource type, such as APPLICATION or FILE.

FieldDefaultDescription
invitation_ttlinvitations.ttlInSeconds (72 hours)The lifetime of a sharing invitation link, in hours.
max_accepted_users10 for APPLICATION, unlimited for other typesThe maximum number of users who can accept an invitation to a shared resource.

Example​

{
  "roles": {
    "default": {
      "limits": {
        "gpt-4o": { "minute": "100000", "day": "2000000" }
      }
    },
    "analyst": {
      "limits": {
        "gpt-4o": {
          "requestHour": "20",
          "requestDay": "300",
          "minute": "200000",
          "day": "10000000",
          "week": "10000000",
          "month": "10000000"
        }
      },
      "costLimit": { "day": 100.0, "month": 2000.0 },
      "share": {
        "APPLICATION": { "invitation_ttl": "24", "max_accepted_users": "10" },
        "FILE": { "invitation_ttl": "24", "max_accepted_users": "10" }
      }
    }
  }
}

Further reading​