Skip to main content

Configure API key authentication

This guide shows how to issue an API key in DIAL Core and scope what it can reach. API keys authenticate server-to-server callers — external applications that call the Unified API directly rather than logging in as a user. For end-user (browser) authentication, use JWT instead.

Prerequisites​

  • A running DIAL Core instance with write access to its dynamic configuration file, config.json.
  • A securely generated random key of at least 128 bits.
tip

You can also create and manage API keys through the DIAL Admin UI instead of editing config.json. See Access management — keys.

Step 1: Define the key​

Add the key to the keys section of config.json. Every key must declare a project and a role — a key without both is invalid.

{
  "keys": {
    "<YOUR_API_KEY>": {
      "project": "MyProject",
      "role": "myRole"
    }
  }
}

DIAL Core reloads config.json automatically (roughly every 60 seconds); no restart is required. For the full attribute list, see the Keys reference.

Step 2: Grant access to resources​

A new key can reach only its own private space and public resources that are not role-restricted. To grant access to a specific deployment, add the key's role to that deployment's userRoles array. The same pattern applies to applications, toolsets, and routes.

{
  "keys": {
    "<YOUR_API_KEY>": {
      "project": "MyProject",
      "role": "myRole"
    }
  },
  "models": {
    "chat-gpt-35-turbo": {
      "userRoles": ["myRole"]
    }
  }
}

Step 3: Restrict by IP range (optional)​

To accept a key only from known networks, list allowed CIDR ranges in keys.<key>.allowedIpAddressRanges. Both IPv4 and IPv6 are supported.

{
  "keys": {
    "<YOUR_API_KEY>": {
      "project": "MyProject",
      "role": "myRole",
      "allowedIpAddressRanges": ["198.51.100.14/24", "2001:db8:1234::/48"]
    }
  }
}

Behavior depends on the value:

  • Unset or null (default) — the key works from any IP address.
  • A non-empty list — the key works only from the listed ranges.
  • An empty list — the key is unusable from any IP address.

A request from an out-of-range address returns 403 Forbidden.

Result​

The key authenticates as project MyProject with role myRole and can call the chat-gpt-35-turbo model. Verify by calling the Unified API with the key:

curl https://<YOUR_DIAL_HOST>/openai/deployments/chat-gpt-35-turbo/chat/completions \
  -H "Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

Further reading​