Automate user provisioning via the API

Onboarding a batch of users through the API touches three resources: users, groups, and the data-source allowlist on each group.

1. Invite a user

POST /api/users
{ "name": "New Hire", "email": "[email protected]", "groups": [4] }

Requires manage_users. An invitation email is sent to the user automatically. The response never includes an api_key — it isn’t usable until the invitation is accepted. See the Users reference.

2. Create a group (if you don’t already have one to invite into)

A group itself carries no permissions — those live on a role, which you attach to the group. Create the group, create a role with the permissions you want, then attach the role:

POST /api/groups
{ "name": "Analysts" }

POST /api/roles
{ "name": "Analyst access", "permissions": ["view_query", "create_query"] }

POST /api/groups/{group_id}/roles
{ "role_id": "<id from the previous response>" }

permissions must be keys from the fixed catalog at GET /api/permissions — see the Permissions & roles reference. See the Groups reference for adding/removing individual members after creation via POST /api/groups/{id}/members.

3. Restrict (or open up) the group’s data-source access

By default a group can reach every data source in the org. To scope a group to an explicit allowlist:

PUT /api/groups/{id}/data_source_access
{ "restricted": true }

Then add each data source the group should reach with POST /api/groups/{id}/data_sources ({"data_source_id": 3}). See the Groups reference.

[!NOTE] A group whose only permission is create_data_source can’t actually create one unless it’s also unrestricted (restricted: false) — there’d be no unrestricted group to attach the new data source to otherwise. See the Data sources reference.

4. Verify what a user can actually do

GET /api/users/{id}/effective_permissions

Admin-only. Returns the flat permission set the user holds via all their groups’ linked roles combined — useful for confirming a provisioning script did what you expected before handing credentials to the user. See the Users reference.