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/jsonIf 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
- Make Your First Mondoo API Request: send a query with the token.
Last updated on