This content is specific to IAM v1. See IAM v2 Overview for IAM v2 specific information.

This guide will show you how to manage Chef Automate users. Import existing users into Chef Automate with Microsoft AD (LDAP), generic LDAP or SAML.

You can create local Chef Automate users that can log in and interact with the system independent of LDAP or SAML.


You will need administrative access to interact with users other than yourself. An existing administrative user can provide that access. If you are already an administrative user, you can create users in the UI by logging into Chef Automate with your admin credentials.


Chef Automate supports three different types of users: local users, LDAP users, and SAML users. Manage local users from the Settings tab.

Manage Local Users from the UI

Navigate to Users in the Settings tab.

To add a local user, use the Create User button, which opens a helper window for entering the user’s full name, a unique username, password and confirm password. Once you’ve filled in the information, use the Save and Close button.

Add Local User

To change or delete a user account, select their name from the Users page. You can also delete users from the Users page by using the menu at the end of the table row.

Modify Local User

Manage Local Users from the Command Line with cURL

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.

To interact with the user API using cURL, fetch an admin API token available from the chef-automate CLI, and set it to a usable variable:

export TOKEN=`chef-automate admin-token`

Create a User

To create a Chef Automate user, you’ll need a name, username, and password. The username must be unique.

curl -H "api-token: $TOKEN" -H "Content-Type: application/json" -d '{"name":"Your Name", "username":"username001rulez", "password":"password"}'

Fetching Users

You can fetch a single user by username. Keep in mind that certain characters in a username (such as a space) may need to be escaped in the URL.

curl -H "api-token: $TOKEN"

More generally, here is the format showing a {username} placeholder:

curl -H "api-token: $TOKEN"{username}?pretty

You can also fetch a list of all users by omitting the final username segment of the URL:

curl -H "api-token: $TOKEN"

Updating Users

You can update a user’s full name (name property) and/or password (password property). To identify the proper user record, supply the username in the URL and the user’s id in the payload. Then, also in the payload, you must specify the full name–even if you do not want to change it! Finally, include the password in the payload, but only if you do want to change it.

curl -X PUT -H "api-token: $TOKEN" -H "Content-Type: application/json" -d '{"name":"Revised Full Name", "id": "userID", "password": "another_pwd"}'{username}?pretty

A non-admin user is also able to change their own password through the UI. For completeness, here is the API call to perform the same action.

curl -X PUT -H "api-token: $TOKEN" -H "Content-Type: application/json" -XPUT -d'{"id":"userID","name":"Revised Full Name","username":"username001rulez","password":"another_pwd","previous_password":"password"}'{username}?pretty

Deleting Users

To delete a user, supply the username:

curl -X DELETE -H "api-token: $TOKEN" -H "Content-Type: application/json"{username}?pretty

User Self-Maintenance

Local Automate users can manage their own name and password through the Chef Automate user interface. Select the user icon in the top navigation bar, then select Profile from the drop-down.

Navigate to user profile

The sidebar should reflect Your Profile as the active panel, and you should see your user name, your avatar (if your username is your email address), and your full name. Use the Edit button to edit your full name, while the lower portion of the page allows you to update your password.

View user details