Skip to main content

Keys

A key is an API key that a service or script uses to call DIAL Core without a user sign-in. Each key belongs to a project, carries one or more roles, and can be limited to client IP ranges. Its roles decide which deployments the key may use and which limits apply. This reference is for platform engineers who issue API keys; it assumes you know Roles.

For when to use API keys instead of identity provider tokens, see API keys.

Where keys are defined​

SourceLocationWhere the secret goes
Config filekeys.<secret>The map key itself is the API key value.
Configuration API/v1/keys/platform/<name>The key field. The name is only an identifier.

Keys are matched by their secret, so a file key and a blob key never shadow each other. In the platform bucket, the secret is stored encrypted and never returned. DIAL Admin manages keys in Keys.

Fields​

FieldRequiredDescription
keyConfiguration API onlyThe API key value. On an update, leaving it out keeps the stored secret.
projectYesThe project the key belongs to.
rolerole or rolesOne role assigned to the key.
rolesrole or rolesSeveral roles assigned to the key.
securedNoWhen true, user requests and deployment responses made with this key are not saved to the prompt log storage.
allowedIpAddressRangesNoIPv4 or IPv6 ranges the key may be used from. Unset or null: any client. Empty list: no client. Otherwise only clients in the ranges. See apiKeyValidation.proxyCount in Access.

Rules for keys in the platform bucket​

  • A PUT without a secret, a project, or a role answers 400.
  • A secret already used by another key, in a blob or a file, answers 409, and the secret is not echoed.
  • Changing the secret revokes the old one at once; deleting the key revokes its secret before Core answers.
  • Migrating a file key names it <project in lowercase>-<first 12 hex characters of the SHA-256 of the secret>, and the secret keeps working. See Configuration API.
  • File keys cannot be read through /v1/admin/config/file/keys; it answers 403 for every caller.

Examples​

In a config file:

{
  "keys": {
    "<API_KEY_VALUE>": {
      "project": "Project1",
      "role": "basic",
      "allowedIpAddressRanges": ["198.51.100.14/24", "2002::1234:abcd:ffff:c0a8:101/64"]
    }
  },
  "models": {
    "gpt-4o": { "userRoles": ["basic"] }
  },
  "roles": {
    "basic": {
      "limits": { "gpt-4o": { "minute": "100000", "day": "10000000" } }
    }
  }
}

Through the Configuration API:

curl -X PUT "https://<DIAL_CORE_HOST>/v1/keys/platform/reporting-service" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"key": "<API_KEY_VALUE>", "project": "Reporting", "roles": ["basic"], "secured": true}'

Further reading​