Create and Manage API Tokens

Create API tokens to authenticate with Mondoo's GraphQL API for custom integrations and automation.

An API token is a bearer token that lets a program authenticate with Mondoo's GraphQL API. Use one in scripts, custom integrations, and any automation that calls the API directly.

A token can be scoped to a single space or to a whole organization (every space in it).

Note: Only team members with Editor or Owner access can perform this task.{" "}

Token permissions

When you create a token, pick the permissions it grants:

Viewer: read most things in the space (or every space in the organization). No changes.
Editor: make changes except deleting the space or organization and except reporting scan results.
Owner: make any change except reporting scan results.
Agent: read and run assigned policy bundles and query packs, and report scan results back. Use this for cnspec agents.

Create an API token

The procedure is the same for space tokens and organization tokens. Start from the scope you want.

Navigate to the space or organization you want the token to belong to.
In the left navigation, select Settings, then the API Tokens tab.
Select the plus symbol on the right of the page.
Give the token a name and short description so future you can tell what it's for.
Check the permissions you want to grant. See Token permissions for what each one allows.
Select GENERATE API TOKEN.
Copy the token value. You won't be able to see it again.

Change a token's permissions

Navigate to the space or organization that owns the token.
In the left navigation, select Settings, then the API Tokens tab.
Find the token in the list and select it.
Select PERMISSIONS.
Update the checkboxes and select SET PERMISSIONS.

Delete a token

Navigate to the space or organization that owns the token.
In the left navigation, select Settings, then the API Tokens tab.
Find the token in the list and select it.
Select DELETE, then DELETE again to confirm.

Rotate tokens

Treat an API token like any long-lived secret: rotate on a schedule, and rotate immediately if you suspect it leaked.

Generate a new token with the same scope and permissions.
Update the application or automation to use the new value.
Confirm the application is working with the new token.
Delete the old token.

For workloads that run in a cloud or CI environment, prefer Workload Identity Federation (WIF) over long-lived API tokens. WIF issues short-lived credentials so you don't have to manage rotation yourself.

API tokens vs. service accounts

Both API tokens and service accounts let non-human callers authenticate to Mondoo, but they're shaped differently:

API tokens are bare bearer tokens. Use them for direct GraphQL API calls and short scripts that can attach an Authorization: Bearer header.
Service accounts return a JSON credential file (a base64-encoded blob containing an MRN, private key, and certificate). Use them for cnspec, CI/CD pipelines, and integrations that expect a config file.