API key scopes

Every Defined Networking API key is granted a set of scopes (also called permission scopes). A scope authorizes an API key to perform one specific action against one resource. Each API endpoint requires a particular scope, so a key can only call an endpoint if it has been granted that endpoint's scope.

Scopes are written as resource:action, for example hosts:read or roles:create. When you create an API key in the admin panel, you choose which scopes it should have. A key can hold any combination of scopes, and a few endpoints require more than one (see Multi-scope endpoints below).

We recommend granting each key the fewest scopes it needs. For example, a monitoring script that only reads audit logs should have audit-logs:list and nothing else. If a key is ever leaked, limited scopes limit the damage — and you should still rotate the key immediately.

Each operation in the API reference lists the exact scope it requires under Token scope required. The tables below summarize every scope an API key can have.

Hosts

Scopes for managing hosts, including lighthouses and relays.

Scope	Grants
hosts:create	Create hosts, lighthouses, and relays.
hosts:read	View the details of an individual host.
hosts:list	List the hosts in your organization.
hosts:update	Edit a host
hosts:delete	Delete a host.
hosts:enroll	Create enrollment codes so a host can be enrolled into the network.
hosts:block	Block a host, cutting off its access to the network.
hosts:unblock	Unblock a previously blocked host.
hosts:debug	Send debug commands to a host.

Roles

Scopes for managing roles and their firewall rules.

Scope	Grants
roles:create	Create a role.
roles:read	View the details of an individual role.
roles:list	List the roles in your organization.
roles:update	Edit a role and its firewall rules.
roles:delete	Delete a role.

Routes

Scopes for managing routes to networks beyond your overlay hosts.

Scope	Grants
routes:create	Create a route.
routes:read	View the details of an individual route.
routes:list	List the routes in your organization.
routes:update	Edit a route.
routes:delete	Delete a route.

Networks

Scopes for managing networks.

Scope	Grants
networks:create	Create a network.
networks:read	View the details of an individual network.
networks:list	List the networks in your organization.
networks:update	Edit a network, including adding CIDRs to it.
networks:delete	Delete a network.

Tags

Scopes for managing tags.

Scope	Grants
tags:create	Create a tag.
tags:read	View the details of an individual tag.
tags:list	List the tags in your organization.
tags:update	Edit a tag.
tags:delete	Delete a tag.

Audit logs

Scope	Grants
audit-logs:list	List audit log entries.

Multi-scope endpoints

Some endpoints require a key to hold more than one scope. If your key is missing any of the required scopes, the request is rejected.

• Create host & enrollment code — requires both hosts:create and hosts:enroll.