What Auth Tokens Can Access
A token is scoped to the level it was created at, which means a parent-level token reaches every child environment. Decide the level before you generate it.
A token is scoped to the level it was created at. That single rule explains every scoping question about API tokens, and it is easiest to get wrong in exactly the organizations where it matters most.
Create a token inside one environment and it reaches that environment. Create it at a parent level and it reaches everything below.
What does that mean for a parent and child structure?
For a service provider or any organization with a parent and child environment hierarchy, a token created at the parent level is granted access to:
- every child environment,
- any shared environment,
- and all global objects.
That is the behavior you want for a tool meant to work across the whole estate, and the wrong behavior for a tool meant to work on one customer. Both are one dropdown apart at creation time.
Which level should I choose?
Pick the narrowest level that does the job, and pick it before you generate, because a token cannot be re-scoped afterwards. Changing scope means creating a new token and revoking the old one, which for an integration in production means a coordinated change rather than an edit.
Two cases worth naming:
An integration serving one customer or one business unit should have a token created in that environment. If it is created at the parent, a bug or a misconfiguration in that integration reaches every environment you have, and nothing about the integration's own configuration would reveal that.
A cross-fleet tool, such as a hunting script or a SIEM enrichment feed, is the case a parent-level token is for.
Remember that scope compounds with the permissions the token already inherits from its creator. See Create and Revoke Auth Tokens. An Admin's token created at a parent level is the broadest credential the platform issues, and it is the easiest one to create by accident.
What should I read next?
- Create and Revoke Auth Tokens, for creating and retiring them.
- Environments, for what a level actually partitions.
- Multi-Tenancy and Organizations, for the parent and child structure this rule is about.
Updated 19 days ago