Skip to main content

Roles & Permissions

Minimal follows a Linux-style user and group model for access control. Roles are not managed by Minimal — they are managed entirely by your existing auth system and passed to Minimal as headers on every request.

Minimal operates in a trusted subsystem model. It does not authenticate users, issue tokens, validate sessions, or maintain a user database. It fully trusts the headers your gateway injects and acts on them directly.

Trusted Subsystem Model​

Your Auth System → validates the user, assigns roles
Your Gateway     → injects identity headers
Minimal          → trusts the headers, enforces role check

Minimal sits behind your gateway and never sees the original token or credential. Your gateway is the trust boundary — Minimal assumes everything it receives has already been authenticated.

Why this model?

You already have an auth system. Minimal does not force you to migrate to a new one, learn a new permission model, or duplicate user management. Bring your own auth — Minimal works with whatever you have.

Scope​

Every request to the Auto API is scoped across six dimensions — all passed as headers:

Organization  (X-Org-Id)
    └── Project      (X-Project-Id)
            └── Space        (X-Space-Id)
                    └── User         (X-User-Id)
                            └── Role         (X-User-Roles)
HeaderExampleDescription
X-Org-Id01KG1G4H4FNHRP7HQRHDGEYAC9Which organization this request belongs to
X-Project-Id01KHR34M1XTX0CH43MASDG9ZC8Which project (database config) to use
X-Space-Id01KBY3K8RQ9GS1VD9XYXHZ92QTWhich workspace within the project
X-User-Id01KBY3K9NDC5XW523M2V1Z0373The authenticated user making the request
X-User-Rolesadmin, usersComma-separated roles assigned to the user

All five are mandatory on every Auto API request. Missing any one returns 400 Bad Request.

Roles​

Minimal recognises two roles out of the box:

RoleAccess
admin
users

Roles are configured in config.yml under auto_api.roles:

auto_api:
  roles: [admin, users]

Only roles listed here are permitted. Any request carrying a role not in this list is rejected with 403 Forbidden.

Your roles, your names

admin and users are defaults — rename them to match your existing auth system. Whatever names you configure in auto_api.roles must match exactly what your gateway sends in X-User-Roles.

Multiple Roles Per User​

A user can carry more than one role — pass them comma-separated:

X-User-Roles: admin, users

Minimal grants the highest privilege among all roles provided.

Your Responsibilities​

Minimal does not manage any of the following — these are entirely owned by your auth system and gateway:

  • User identities and accounts
  • Role assignment per user
  • Which users can access which org, project, or space
  • Token issuance and validation
  • Session management
What your gateway should do
  1. Validate the incoming user token — JWT, session cookie, API key, whatever your system uses
  2. Resolve the user's org, project, space, and roles
  3. Inject all five headers before forwarding to Minimal
  4. Never forward unauthenticated requests to Minimal

Minimal only ever sees the injected headers — it never sees the original credential.

Example — Admin privilege​

curl 'https://your-domain.com/minimal/api/rest/auto/v1/ms/demo_db/users?pg=0&ps=10' \
  --header 'X-Org-Id: 01KG1G4H4FNHRP7HQRHDGEYAC9' \
  --header 'X-Project-Id: 01KHR34M1XTX0CH43MASDG9ZC8' \
  --header 'X-Space-Id: 01KBY3K8RQ9GS1VD9XYXHZ92QT' \
  --header 'X-User-Id: 01KBY3K9NDC5XW523M2V1Z0373' \
  --header 'X-User-Roles: admin'

Full access — GET, POST, PUT, DELETE all permitted.

Common Errors​

CodeCauseFix
400 Bad RequestOne or more of the five required headers are missingEnsure your gateway injects all five headers on every request
401 UnauthorizedX-User-Id is missingAlways pass X-User-Id — Minimal requires it on every request
403 ForbiddenRole not permitted for this HTTP methodCheck X-User-Roles matches a role in auto_api.roles and has permission for the operation