Create and Manage API Tokens

API tokens let you communicate with Mondoo's GraphQL API. With API tokens, programs can authenticate with the Mondoo API, which is useful for incorporating Mondoo in different workflows and automation.

The API token you generate can provide access to a single space or all spaces within an organization.

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

Generate an API token for access to a single space

1. Navigate to the space in which you want to create an API token.

2. In the left navigation, select Settings. Then select the API Tokens tab.

3. Select the plus symbol on the right of the page.

   

4. Enter a unique name and description for the token that helps you recognize its purpose.

5. Check the Mondoo permissions you want to give to programs that use this token:

   • Viewer permissions let the program browse most information in the space but not make changes.

   • Editor permissions let the program make all changes possible in the space except deleting the space or reporting scan results.

   • Owner permissions let the program make all changes possible in the space except reporting scan results.

   • Agent permissions let the program read and use policy bundles and query packs and report the results to the space.

6. Select GENERATE API TOKEN.

Generate an API token for access to all spaces in an organization

1. Navigate to the organization in which you want to create an API token.

2. In the left navigation, select Settings. Then select the API Tokens tab.

3. Select the plus symbol on the right of the page.

   

4. Enter a unique name and description for the token that helps you recognize its purpose.

5. Check the Mondoo permissions you want to give to programs that use this token:

   • Viewer permissions let the program browse most information in all spaces in the organization but not make changes.

   • Editor permissions let the program make all changes possible in all spaces in the organization except reporting scan results or deleting the organization or spaces.

   • Owner permissions let the program make all changes possible in all spaces in the organization except reporting scan results.

   • Agent permissions let the program read and use policy bundles and query packs and report the results to spaces in the organization.

6. Select GENERATE API TOKEN.

Change an API token's permissions

1. Navigate to the organization or space containing the API token.

2. In the left navigation, select Settings. Then select the API Tokens tab.

3. Search for or scroll to the API token you want to change and select it.

   

4. Select the PERMISSIONS button.

   

5. Change the permissions as desired. To learn about each permission, read the previous sections.

6. Select the SET PERMISSIONS button.

Delete an API token

1. Navigate to the organization or space containing the API token.

2. In the left navigation, select Settings. Then select the API Tokens tab.

3. Search for or scroll to the API token you want to delete and select it.

   

4. Select the DELETE button and select the DELETE button to confirm.

Rotate API tokens

Treat API tokens like any other long-lived secret: rotate them on a schedule and immediately if you suspect compromise. To rotate a token:

1. Generate a new token with the same scope and permissions, as described in the relevant section above.

2. Update the application or automation that uses the token to use the new value.

3. Verify the application is working with the new token.

4. 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 where the caller 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.