API Tokens

Chef Automate has two different types of API tokens: administrative and standard. With an administrative token you can access the entire Chef Automate API–including administrative tasks such as managing local users and teams and managing authorization policies. Standard tokens have much more limited permissions; they are designed for Chef Clients and InSpec Agents to send data to Chef Automate. You can also use a standard token to access any part of the Chef Automate API if you write a policy granting it specific access. However, granting a user access to the auth:tokens resource also gives that user access to the administrative token.

Before you follow these instructions, we recommend you install the JSON processor jq to ensure readable output. Without it, some commands may need to be modified.

Creating an Admin API Token

To create an Admin API token with global access to the API, you’ll need to log onto your Chef Automate installation and use the chef-automate CLI command:

chef-automate admin-token

This command outputs your new token to the terminal.

To create an admin token and immediately store it in an environment variable for easy access, you can instead run:

export TOK=`chef-automate admin-token`
echo $TOK

Once you have an Admin API token, you can use it to make requests by passing it in the api-token header:

curl -s -H "api-token: $TOK" https://automate.example.com/api/v0/auth/policies -v

If you have Admin level access to the API, you can retrieve your token at any time by going to https://automate.example.com/admin/tokens and looking for a token with the description:

This token was generated by the chef-automate CLI tool. It has admin level access on the entire Chef Automate API.

You can then copy into your clipboard by clicking the clipboard icon.

Creating a Standard API Token

Create tokens with lower access levels or for Chef Client and Inspec data reporting through the user interface or the API. By default, these tokens only have access to data collection API endpoints. To use them outside the context of Chef Clients and InSpec Agents, you’ll need to create a policy for your token.

Creating a Standard API Token via the User Interface

Go to https://automate.example.com/admin/tokens in your browser and click Add new API Token. You must be an Admin to perform this action, see default policies for more information.

You can give the token a description. It will show up in the table and it can be copied to your clipboard.

Creating a Standard API Token via the API

If you already created an Admin API token, you can create a standard API token via the API. You can give it a description to denote its use:

curl -s -H "api-token: $TOK" -H "Content-Type: application/json" -d '{"description":"My shiny new token"}' https://automate.example.com/api/v0/auth/tokens | jq .id

Permissioning a Standard API Token

Grant your API tokens access to some or all of the API by creating a policy for the token. One common example of creating a policy is granting a client’s API token access to all of the Compliance API. See Authorization for more information about authorization and policies.

Granting a user access to the auth:tokens resource also gives that user access to all tokens, including the administrative token.

As an admin, I would like to create a token that gives a client permission to read any compliance resource.

  1. Get an Admin API token and save it in the environment variable $TOK:
   export TOK=<your_admin_api_token>
  1. Create a standard API token to permission.

  2. Copy the token returned.

  3. Create policies to permit that client to read compliance:*. For more information, see policies.

   export TOK=<your_admin_api_token>
   curl -s -H "api-token: $TOK" -H "Content-Type: application/json" -d '{"subjects":["token:95aef20b-0a4e-4698-bd69-ce2cf44c2e35"], "action":"read", "resource":"compliance:*"}' https://automate.example.com/api/v0/auth/policies | jq