Skip to Content
GraphQL API

Authenticate with the Mondoo API

Create an API token, send it in the Authorization header, and give it only the permissions your script needs.

Every request to the Mondoo API needs a credential. For scripts and tools that call the API directly, use an API token.

Create an API token

An API token is a bearer token that belongs to one space or one organization:

  • A space token can read and change data in that space only.
  • An organization token can read and change data in the organization and in every space it contains.

Create the token at the narrowest scope your script needs. To create one, read Create an API token. Copy the value when Mondoo shows it, because you can't see it again.

Store the token in an environment variable or a secret manager, never in your source code. The examples in this section read it from MONDOO_API_TOKEN:

export MONDOO_API_TOKEN='YOUR_API_TOKEN'

Send the token with every request

Pass the token and the content type as headers on every request:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

If the token is missing, invalid, or deleted, Mondoo rejects the request before it reaches GraphQL. To learn what those responses look like, read Errors.

Give the token only the access it needs

When you create a token, you pick its role and permissions the same way you pick a team member's. A token can never have more access than the person who creates it.

  • Read data: The Viewer role can read assets, findings, vulnerabilities, exceptions, tickets, and integrations. Give read-only scripts this role.
  • Change data: Add only the permissions for the changes your script makes. For example, a script that creates exceptions needs Viewer plus Exception Requester, and a script that deletes assets needs Viewer plus Asset Manager. Each recipe in this section names the access it needs.

To see every role and permission, read Roles and permissions. To change the access of an existing token, read Change a token's permissions.

Rotate tokens

Rotate API tokens on a schedule, and right away if you suspect one leaked. To learn how, read Rotate tokens.

Other credentials

For direct HTTP calls like the examples in this section, use an API token. Mondoo has two other kinds of non-human credentials, which Mondoo tools use:

  • Service accounts are JSON credential files with a private key. Tools that understand them, such as cnspec and the Mondoo Terraform provider, use them to authenticate.
  • Workload identity federation (WIF) lets workloads in AWS, Azure, Google Cloud, GitHub Actions, and other OIDC environments authenticate without a stored secret. Use it for cnspec in CI pipelines and cloud workloads.

To compare all three, read Grant Services, Scripts, and Apps Access to Mondoo.

Next steps

Last updated on

On this page