Teams and sharing

Teams are engine-owned groups inside one organization. Membership names principals, and access is evaluated against the current roster on every check.

Create a team

An organization administrator creates and manages teams:

curl -s "$BASE_URL/v1/teams" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support"}'

Use the returned team UUID for membership and grants.

Add a member

Obtain the person's engine principal UUID from their GET /v1/me/usage response or from the platform administrator. Never use the identity provider's sub.

curl -s "$BASE_URL/v1/teams/$TEAM_ID/members" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"user_id\":\"$PRINCIPAL_ID\"}"

Grant a resource

Dataset and project grants accept user, role, and team principals. A team grant is an upsert: a new grant returns 201; changing or repeating an existing grant returns 200 and records the old and new permission in audit.

curl -s "$BASE_URL/v1/datasets/$DATASET_ID/grants" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"principal_type\":\"team\",\"principal_id\":\"$TEAM_ID\",\"permission\":\"read\"}"

The same shape applies under /v1/projects/{id}/grants.

Change or remove access

• Removing a member takes effect on the next authorization check; no token refresh is required.
• Deleting a team removes grants that name it.
• Team grants do not apply to model entitlements. Model grants remain organization, role, or user scoped.
• Only organization administrators mutate rosters. Members may list teams visible to them.