Skip to main content
Applies to:
  • Plan - Any
  • Deployment - Any
  • Use case - Audit ACLs by mapping UUID grants to human users or service accounts

​
Summary

ACL entries show raw UUIDs instead of names. These UUIDs are the user or service account IDs for the grant. Use an org-scoped API key for the Braintrust instance where you exported the ACLs. Call GET /v1/user and GET /v1/service_token and match the UUIDs to the id or service_account_id fields.

​
What is happening

ACL records store principals as UUIDs. The UUID identifies either a human user or a service account in that instance.
  • GET /v1/user returns human users with id, email, given_name, and family_name.
  • GET /v1/service_token returns service tokens with service_account_id (the account user ID, not the token ID).

​
Resolution

Set BRAINTRUST_API_URL to your org’s API URL for self-hosted deployments, or https://api.braintrust.dev for Braintrust-hosted orgs.

​
Human users

Call GET /v1/user and match ACL user_id to objects[].id. The response also includes email, given_name, and family_name.
Paginate with limit and starting_after for large orgs.

​
Service accounts

For UUIDs not found in /v1/user, call GET /v1/service_token (org owner key required) and match ACL user_id to objects[].service_account_id, not the token’s id.

​
Expected results

  • Human user: matched object includes email, given_name, and family_name.
  • Service account: matched object includes service_account_name and service_account_email.
  • Still unresolved: check the ACL’s role_id, or go to Settings > Project permissions. The Service accounts tab lists every service account with access, including internal ones (such as online scoring) and custom accounts you created.

​
Notes

  • If auditing across multiple environments, repeat the lookup in each. User IDs are not shared across instances.
  • /v1/service_token only lists accounts with tokens. Some auto-created accounts will not appear.
  • GET /v1/user/{id} returning ForbiddenError can mean the UUID is a service account, but it can also mean the user was deleted, the UUID is wrong, or you queried the wrong API URL or org. Confirm with GET /v1/service_token or the UI before treating it as a service account.