API key

An API key is a secret token that lets a script or tool, such as the Terraform provider, call the Defined Networking API on behalf of your account. You send it as a bearer token in the Authorization header of each request.

Every key is granted a set of scopes, written as resource:action, such as hosts:create or audit-logs:list. A key can only call the endpoints its scopes allow, so give each key the fewest scopes it needs. API key scopes lists every scope and the endpoints that need more than one.

API keys are on the Settings > API keys page of the admin panel. When you add a key, you give it a name, choose an expiration (30 days by default, or 7, 90, or 365 days, a custom date, or no expiration), and select its scopes. The token starts with dnkey- and is shown only once, right after you save, so store it somewhere safe. The expiration can’t be changed after the key is created.

Keys aren’t rotated automatically. If a key may have leaked, create a new one with the same scopes, update your scripts, and revoke the old one, as described in Rotating API keys. Changes made with a key show it as the actor in the audit log.

For creating and enrolling hosts from a script, see Automating host creation. If every machine should join with the same settings, a join key needs no API key at all.