Authorization

Spiral uses a role-based access control (RBAC) model for authorization, where currently the only unit of permissioning is the project.

In this model, principals (users, teams, workloads) are granted roles on projects.

A role confers a set of permissions on the project, which are used to determine whether a principal is allowed to perform a given action.

Roles

The roles currently defined in Spiral are:

• admin - full access to the project
• editor - read/write access to the project
• viewer - read-only access to the project

These roles expand to resource-specific permissions, such as table:read and table:write.

Please reach out to us if you have specific requirements for custom roles.

Principals

Principals are entities that can be granted roles on projects. Currently, the following types of principals are supported:

• Org-scoped Users - an individual org/user pair
• Teams - groups of users as defined manually in Spiral
• Groups - groups of users as synchronized from an external identity provider
• Organizations - a team implicitly defined as all members of an organization
• Workloads - non-human entities. Workloads authenticate via OIDC, AWS IAM, or client credentials. See Workloads below and the OIDC Integrations page for setup instructions.

Grants

Grants are the association of a principal with a role on a project. They are the mechanism by which permissions are conferred. Grants can be listed, created, updated, and deleted using the Spiral CLI. To create a grant, see grant command.

Workloads

Workloads are non-human principals in Spiral — they represent services, jobs, or automations that need to access data. Workloads are managed via the spiral workloads set of CLI commands.

If workloads write to resources in a single project, it is recommended that they be placed in that project. If workloads modify multiple projects, it is recommended to keep them in a separate project from all resources.

A workload can authenticate using either a policy (OIDC or AWS IAM) or client credentials.

Policies

A workload policy maps an external identity to a Spiral workload. This is the recommended approach — it avoids managing static credentials and integrates with your existing identity provider.

Authenticating a workload with a policy requires the following steps:

1. Create a workload — spiral workloads create
2. Create a workload policy — a policy maps claims from your identity provider’s tokens to the Spiral workload. The policy specifies conditions (key=value pairs) that must match the token’s claims.
3. Grant the workload a role on a project, so it can access data.
4. Set SPIRAL_WORKLOAD_ID in the environment where you use the pyspiral library.
5. Configure your identity provider — see the OIDC Integrations page for provider-specific setup.

OIDC

OIDC  is a protocol for authenticating entities between systems. We strongly recommend using OIDC for workload authentication — it is easier to set up and more secure than managing static credentials.

Spiral integrates with several OIDC providers. Check out the OIDC Integrations page for available integrations and how to set them up.

Client Credentials

When a workload policy is not possible (e.g. the environment does not provide OIDC tokens), you can issue client credentials instead.

1. Create a workload — spiral workloads create
2. Issue credentials — spiral workloads issue-creds <workload_id>. This outputs a SPIRAL_CLIENT_ID and SPIRAL_CLIENT_SECRET. The secret is shown only once.
3. Grant the workload a role on a project: spiral projects grant <project_id> --role viewer --workload-id <workload_id>
4. Set SPIRAL_CLIENT_ID and SPIRAL_CLIENT_SECRET in the environment where you use the pyspiral library.