StudioHomepage
ServicesAuthorization

Grant Project access

Give users, Organization roles, and workloads a Project role, then inspect and revoke grants.

Available

Give each person and pipeline the narrowest Project role that covers their work. You can grant a role to one user, to everyone with an Organization role (now and in the future), or to a workload such as nightly-curation. Until you do, Organization members cannot see the Project's data; see Authorization for the roles and the grants a new Project starts with.

Prerequisites

  • You have the Project admin role.
  • You know your Organization ID (org_...). spiral orgs ls lists it.

Grant a role to one user

Find the person's user ID (user_...) with spiral orgs users ls, then grant the role:

principal = AuthorizationPrincipal(
    organization_user=AuthorizationOrganizationUserPrincipal(organization_id=organization_id, user_id=user_id)
)
request = AuthorizationGrantRoleRequest(role="editor", principal=principal)
grant = client.authorization.grant_role("demo", request).grant
print(f"granted {grant.role} as {grant.id}")

Grant a role to everyone with an Organization role

A grant to an Organization role applies to every user with that role, now and in the future.

principal = AuthorizationPrincipal(
    organization_role=AuthorizationOrganizationRolePrincipal(organization_id=organization_id, role="member")
)
request = AuthorizationGrantRoleRequest(role="viewer", principal=principal)
grant = client.authorization.grant_role("demo", request).grant
print(f"granted {grant.role} as {grant.id}")

Grant a role to a workload

Find the workload ID (work_...) with spiral workloads ls, then grant the role. A pipeline that writes Tables needs editor:

principal = AuthorizationPrincipal(workload=AuthorizationWorkloadPrincipal(workload_id=workload_id))
request = AuthorizationGrantRoleRequest(role="editor", principal=principal)
grant = client.authorization.grant_role("demo", request).grant
print(f"granted {grant.role} as {grant.id}")

Inspect and revoke grants

List the grants of a Project, read one grant, and revoke a grant by ID. Listing and revoking grants also require the Project admin role.

for grant in client.authorization.list_grants_items("demo"):
    print(f"{grant.id}: {grant.role} for {grant.principal}")

grant = client.authorization.read_grant(grant_id)
print(f"{grant.id} grants {grant.role} on {grant.project_id}")

client.authorization.revoke_grant(grant_id)
print(f"revoked {grant_id}")

Verify a grant

Sign in as the principal, then list Projects. The list contains only the Projects that the principal can view. For a workload, set its credentials in the environment first. See Workloads.

spiral whoami
spiral projects ls

Troubleshooting

ErrorCauseFix
Invalid org_id in principalThe Organization ID does not start with org_.Copy the ID from spiral orgs ls.
Invalid user_id in principalThe user ID does not start with user_.Copy the ID from spiral orgs users ls.
Invalid workload_id in principalThe workload ID does not start with work_.Copy the ID from spiral workloads ls.
A permission errorYou do not have the Project admin role.Ask a Project admin for the grant.

Where next: create a workload for a pipeline.

Found a problem? Edit this page or report an issue.

On this page