Roles & permissions

LakeSail has three layers of access control. From broadest to narrowest:

Layer	What it grants	Where it attaches
Organization roles	Permissions across the whole org	Member
Team roles	Permissions within one team's resources	Member, per team
Authorization policies	Specific permissions on specific resources	Member or team

You don't have to use all three. Most orgs do all of their access control with org roles + team roles; policies are an escape hatch for one-off cases.

Organization roles

Organization roles are pre-defined permission bundles that apply across the entire organization. Examples include the admin role (full org control) and various scoped roles for specific functions. Browse the catalog at Settings → Roles → Organization Roles — you can read the role definitions and see what each one grants, but you can't create new ones; the role catalog is fixed by the platform.

Each organization role has an allTeams flag:

• allTeams: false — the role grants org-wide permissions but doesn't add the member to teams. Useful for billing or audit roles that need to see but not own anything.
• allTeams: true — the role automatically adds members to every team in the org. This is how "Org Admin" works in practice — any member who holds it gets admin-level access to every team's resources without any per-team setup.

To assign an org role: open Settings → Members, click the member, and edit their org roles.

Team roles

Team roles are permission bundles that apply only inside one team. The same member can hold a different team role for each team they belong to — admin in data-eng, contributor in analytics, viewer in platform.

Like org roles, the team role catalog is fixed by the platform. Browse it at Settings → Roles → Team Roles.

Common team roles you'll see:

• An admin-style role — full control over the team's resources and membership.
• A contributor-style role — create, edit, and run resources owned by the team.
• A viewer-style role — read-only access.

To assign a team role: open the team, find the member, and pick the role.

Choosing between org roles and team roles

A simple rule:

• Org role when the permission applies to the whole org regardless of which team you're looking at — billing, IdP setup, viewing audit logs, "admin everywhere."
• Team role when the permission is scoped to specific resources — managing prod jobs, running ETL, viewing analyst queries.

If you find yourself assigning an org role to most members "just so they can see things," prefer giving them a team role on the relevant team. Org roles should stay narrow.

Authorization policies

Authorization policies are the fine-grained escape hatch. A policy is a list of specific permissions granted to a specific principal (a member or a team).

Each permission is a relation like CanManageUsers, attached to a resource type (organization, team, etc.). The set of available permissions is published at the Permissions endpoint (/auth/permissions); each one carries a description and the resource types it applies to.

Use a policy when:

• You need to grant exactly one permission to one person without elevating their role.
• You need to grant access to a single resource (a specific job or catalog) without making someone a team member.
• A role doesn't include a permission you need, or includes permissions you don't want to grant.

Manage policies at Settings → Authorization Policies (or the per-resource policy controls). Each principal has at most one organization-level policy; updating it replaces the existing list of permissions.

Use sparingly

Policies are powerful but hard to audit. A reviewer asking "who can manage users?" can scan org-role assignments quickly; finding answers across hundreds of policy records is slow. Prefer roles when the bundle of permissions you'd grant matches a role.

How permissions actually resolve

When a member tries to do something, LakeSail checks each layer:

1. Does any organization role the member holds grant this permission?
2. For team-scoped resources, does any team role the member holds on the relevant team grant this permission?
3. Does an authorization policy for this member (or for a team they're on) explicitly grant this permission, possibly on this specific resource?

If any layer says yes, the action is allowed. There's no explicit deny — removing a permission means removing it from every layer that granted it.

Reviewing access

For routine access reviews:

1. Who can do what at the org level? Open Settings → Members and group by org role.
2. Who can do what to a specific resource? Open the resource and check the owning team's membership, plus any shared teams' membership, plus any direct policies.
3. What does this role actually grant? Open the role detail page; the permission bundle is shown.

If you find that the same person holds inconsistent levels of access via different paths (e.g. team role says read, policy says write), simplify by removing the redundant grant — keep one source of truth per permission.

Configuring SSO group → role mapping

If you connect an identity provider with group claims, group memberships from your IdP can map onto LakeSail org roles or team memberships.

This is the cleanest pattern for larger organizations: define groups in your IdP (Okta, Entra ID, Google Workspace), map them to LakeSail roles, and let the IdP be the source of truth for who's on what team.

API reference

• Roles — list and describe organization and team roles.
• Authorization Policies — PutOrganizationPolicy, DescribeOrganizationPolicy, DeleteOrganizationPolicy for fine-grained grants.
• Authentication — ListPermissions for the catalog of available permission relations.