Identity and access
How Hexel Studio identifies people and workloads, organizes resources, and decides whether a request is allowed.
Identity and access is the part of Hexel Studio that answers three questions for every API request: who is calling, which organization the call is for, and whether the caller may do it. It covers your Hexel account, your organizations and their workspaces and environments, the members and machine identities in them, and the policies that grant access.
Create an organization, get a token and make your first API call.
Tokens for people, API keys and OAuth clients for services.
The building blocks
| Block | What it is |
|---|---|
| Hexel account | You, as a person. You sign in with your email, a passkey, Google or GitHub, and the same account can belong to several organizations. |
| Organization | The top-level container for resources, members, policies and billing. Every API call is made for exactly one organization. |
| Workspace | A group of resources inside an organization, for example one per team or product. |
| Environment | A stage inside a workspace, such as Production or Development. |
| Member | A Hexel account that belongs to an organization. |
| Service user | A non-human identity owned by an organization, for scripts, servers and CI. It signs in with an API key or an OAuth client. |
| Group | A set of members that share policies. |
| Role | An identity that a member, a service user or another role can assume to get its permissions for a limited time. |
| Policy | A JSON document that lists the actions it allows. You attach it to a member, a group, a service user or a role. |
When you create an organization, Hexel Studio also creates a Default workspace with a Production and a Development environment, and makes you its owner.
How a request is decided
Every call to https://api.hexelstudio.com/v1/... goes through the same checks, in order:
- Authentication. The request carries a Hexel Studio access token (
Authorization: Bearer ...) or an API key (X-API-Key). A token is short-lived and belongs to one identity in one organization. - Organization. The organization comes from the token. If you also send
X-Organization-Id, it must match. - Permission. A policy that applies to the caller must allow the action, for example
workspace:workspace:create. A policy applies when it's attached to the caller or to a group the caller is in, or, in a role session, attached to the role. Anything not allowed is denied. - Plan limits. Some actions also count against a limit of your organization's plan, such as the number of workspaces or members. A request over a limit is refused even when the caller is allowed.
A permission never comes from a name, an email address or a header you send. It comes only from policies attached in the organization the token is for.