How do I properly create an API token for Ingest or Compliance Read access in Chef Automate?

How to Create an Ingest Token?

How to Create a Compliance Read Token?

 

Chef Automate authenticates REST API calls using API Tokens. Tokens carry no permissions on their own — access is controlled by IAM Policies that the token is added to as a member. This guide shows you how to create correctly scoped service tokens for two common use cases:

• Ingest token — lets Chef Infra Server, Chef Infra Client, and InSpec push run and compliance data to Automate's data-collector endpoint.
• Compliance Read token — lets external tooling read compliance scan results and reports without write or administrative access.
• Combined token (e.g. Chef 360) — Chef Automate tokens can have multiple policies assigned. Integrations like Chef 360 use a single token for both data ingest and compliance profile reading, requiring both Ingest and Compliance Viewers policies on one token.

 

Pre-Requisites 

• You need a user account with the iam:tokens permission. Members of the built-in admins team or the Administrator policy have this by default.
• You do not need access to the chef-automate CLI for either token type in this guide.

Do not use admin tokens for service accounts. Admin tokens (full access) can be created via CLI (chef-automate iam token create <name> --admin) and must never be used for ingest or reporting integrations.

 

 

How to Create an Ingest Token

Chef Automate includes a built-in ingest role and a matching Ingest policy. You only need to create a token and attach it to that policy — no custom policy is needed.

 

Step 1: Create and assign the token

1. 1. Go to Settings → API Tokens and select Create Token.
   2. Enter a descriptive name such as infra-server-ingest-prod. A token ID is generated automatically; you can edit it before saving.
   3. Under Policies, assign the token to the Ingest Chef-managed policy.
      • If you're using IAM projects to scope ingested node or compliance data, optionally assign the token to the relevant Project here as well.
   4. Select Create Token.
   5. In the token list, open the row menu (⋮) and select Copy Token or Show Token to view the token value at any time.

 

Step 2 (if skipped above): Assign the policy after creation

1. 1. Go to Settings → Policies → Ingest.
   2. Select Members → Add Members → Add Member Expression.
   3. Enter token:<token-id> (the token ID is visible on the API Tokens page).
   4. Save.

 

Step 3: Configure your tools to use the token

Consumer	Configuration
Chef Infra Server	Set data_collector['token'] and data_collector['server_url'] in /etc/opscode/chef-server.rb, then chef-server-ctl reconfigure.
Chef Infra Client	Set data_collector.token and data_collector.server_url in client.rb on each node.
InSpec	Configure --reporter automate with the token and Automate URL, either in InSpec's config file or via environment variables (syntax varies by InSpec version).
Chef360	Connector configuration for Chef Automate using API token https://community.progress.com/s/article/How-to-configure-the-Automate-Connector-in-Chef-360-Platform-using-the-API

 

 

How to Create a Compliance Read Token

Chef Automate has no built-in role scoped exclusively to compliance read access. The default viewer role (used by the Viewers policy) grants broad read access across all of Automate, not just Compliance. Choose one of the two options below based on how strictly you need to limit scope.

 

Option A: Use the existing Compliance Viewers policy (fastest)

Chef Automate includes a Compliance Viewers custom policy that covers read-only compliance access out of the box.

1. 1. 1. Go to Settings → Policies → Compliance Viewers and review its statements. Confirm the policy grants only compliance:*:get and compliance:*:list actions and nothing broader. Adjust if needed.
      2. Go to Settings → API Tokens → Create Token.
      3. Enter a name such as compliance-read-external-tool.
      4. Under Policies, assign the token to Compliance Viewers.
      5. Select Create Token, then copy the token value from the row menu.
   2.  Note: Because Compliance Viewers is a custom policy, any admin can modify it. If policy drift is a concern, prefer Option B.

 

Option B: Create a custom role and policy (recommended for strict least-privilege)

Custom roles cannot be created in the Automate UI. Use the IAM Roles API with an admin token to create one:

curl -sS -k -w "\nHTTP Status: %{http_code}\n" -X POST \
  "https://${AUTOMATE_URL}/apis/iam/v2/roles" \
  -H "api-token: ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "compliance-read-only",
    "name": "Compliance Read Only",
    "actions": [
      "compliance:*:get",
      "compliance:*:list"
    ]
  }'

Flags explained:

• • -sS — suppresses the progress meter but still prints curl-level errors
  • -k — skips TLS certificate verification (required for self-signed certs common in Automate deployments; omit if you have a valid CA-signed cert)
  • -w "\nHTTP Status: %{http_code}\n" — prints the HTTP response code so you can tell 201 Created from 400/403/409

Common failure codes:

Code	Cause
403	${ADMIN_TOKEN} does not have iam:roles:create permission - use an admin token
400	Malformed JSON or unsupported action pattern
409	A role with id compliance-read-only already exists — check with GET /apis/iam/v2/roles
000	curl TLS error -  add -k or fix your cert path

Then create a custom policy that references this role and add the token as a member using the expression token:<token-id>. You can do this via the Policies API or through the UI once the policy exists.

 

Step 2: Use the compliance read token

Pass the token in the api-token HTTP header on any compliance reporting API call:

curl -s \
  "https://${AUTOMATE_URL}/api/v0/compliance/reporting/reports" \
  -H "api-token: ${COMPLIANCE_TOKEN}"

 

How to Create a Token for Chef 360 (Combined Ingest & Compliance)

Chef 360 connects to Chef Automate via a single connector configuration — it does not support separate tokens for node ingest vs compliance profiles. Therefore, the single token used for Chef 360 must be assigned both roles/policies.

In Chef Automate, a single token can be assigned to multiple policies.

Steps for Chef 360 Token Setup

1. 1. Go to Settings → API Tokens and select Create Token.
   2. Name it (e.g. chef360-automate-connector).
   3. Under Policies, select both of the following policies:
      • Ingest (Chef-managed policy for data collector ingestion)
      • Compliance Viewers (or your custom compliance read policy)
   4. Select Create Token.
   5. Copy the token value from the row menu (⋮ → Copy Token or Show Token).
   6. Use this token in your Chef 360 Automate connector setup.

 

How to Store the Token Value Securely

• Chef Automate allows users with permissions to view or copy existing tokens at any time from Settings → API Tokens using the row menu.
• Store tokens in a dedicated secrets manager (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or equivalent). Do not embed them in plaintext CI variables, committed config files, or client.rb.
• For services managed by Chef Habitat, do not store tokens in default.toml or user.toml. Habitat's Supervisor exposes all cfg values in plaintext via its HTTP gateway (/services/{name}/{group}/config) and provides no field-level redaction. Fetch secrets at runtime from your secrets manager inside the service's init or run hook.

 

Summary

Token purpose	Recommended path	Chef-managed asset
Ingest (Infra/Compliance data push)	Attach to the built-in Ingest policy	ingest role · Ingest policy
Compliance Read	Attach to Compliance Viewers policy (Option A) or create a custom compliance:*:get/list role (Option B)	Compliance Viewers custom policy
Chef 360 Connector	Attach to Ingest AND Compliance Viewers policies	Ingest policy + Compliance Viewers policy

Service account tokens should always be scoped to the minimum permissions required. Never use an admin-level token (--admin) for automated ingest or reporting integrations.

 

 

References:

Chef Automate Connector - https://docs.chef.io/360/1.7/chef_360_ui/connector/automate_connector/

API Tokens - https://docs.chef.io/automate/api_tokens/