User Roles

Self-Hosting Documentation Access

This section requires a password to access. Interested in self-hosting? Contact sales to learn more.

Password:

Access Documentation

Self-Hosting Documentation Access Granted Logout

Each organization member in your LlamaCloud deployment holds a role that controls what they can do:

• Admin — full access to the organization and its projects.
• ViewerV2 (shown as “Viewer” in the UI) — read-only. Viewers can browse projects and resources and read job results, but requests that create or modify anything are rejected with a 403.

The role named Viewer is an older role that still permits some write operations — don’t use it for read-only members; use ViewerV2.

The IS_VIEWER_V2_ROLE_ENABLED feature flag (on by default) controls whether ViewerV2 appears in the roles listing below. It gates discovery only: roles already assigned keep working, and the read-only enforcement itself is unconditional. If your deployment disables the flag, re-enable it before provisioning read-only members.

Provision members with a role over the API

Managing members over the API requires an API key belonging to an organization admin. Set up your environment first:

export LLAMA_CLOUD_API_KEY="<org-admin-api-key>"
export HOST="https://<your-llamacloud-host>"
export ORG_ID="<your-organization-id>"   # shown on the Organization Settings page

Look up the role ID

Role IDs are generated per deployment, so look the role up by name rather than hardcoding an ID. The ID is stable within a deployment, so this is a one-time lookup:

export ROLE_ID=$(curl -s "$HOST/api/v1/organizations/$ORG_ID/roles" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  | jq -r '.[] | select(.name=="ViewerV2") | .id')

Add members

The request body is an array, so add several members in one call. Member additions are rate-limited per organization, so prefer one batched request over calling in a loop. project_ids controls scope: null grants access across the whole organization, while a list of project IDs restricts the member to those projects:

curl -X PUT "$HOST/api/v1/organizations/$ORG_ID/users" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{ "email": "person@example.com", "project_ids": null, "role_id": "'"$ROLE_ID"'" }]'

Adding by email works before the person has signed up: the invite is stored and redeemed automatically when they sign up with that email address. Responses to email-based additions always list the member as pending.

Remove a member

Remove a member by email or by user ID:

curl -X DELETE "$HOST/api/v1/organizations/$ORG_ID/users/person@example.com" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"