auth — RBAC authorization service

Role-based access control over HTTP. auth answers one question — may user X do Y — so your services don't reinvent roles and permissions.

It is authorization, not authentication: it does not log anyone in, store passwords, or issue tokens. It trusts that the caller already knows who the user is, and decides what they may do. Model: user → (member of) → role → (holds) → permission.

Quickstart

Your client key is any UUID4 — it is also your private, isolated namespace. Generate one, keep it secret, and reuse it for every call. A role must exist before you add members or permissions to it.

KEY=$(python3 -c "import uuid; print(uuid.uuid4())")
BASE=https://auth.rodmena.app

curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/role/engineers
curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/permission/engineers/deploy
curl -X POST -H "Authorization: Bearer $KEY" $BASE/api/membership/alice/engineers
curl        -H "Authorization: Bearer $KEY" $BASE/api/has_permission/alice/deploy
# -> {"success": true, "data": {"has_permission": true}, ...}

With the Python client (pip install auth):

from auth import Client

with Client(api_key=KEY, service_url="https://auth.rodmena.app") as c:
    c.create_role("engineers")
    c.add_permission("engineers", "deploy")
    c.add_membership("alice", "engineers")
    c.user_has_permission("alice", "deploy")   # -> {... "has_permission": true}

Things to know before you write code

• Writes can return HTTP 200 with {"result": false} (e.g. adding to a missing role). Check the result/data field, not just the status code.
• Two response shapes — bare {"result": ...} and wrapped {"success", "data", ...}. The API reference says which per endpoint.
• Errors below 2xx are HTML, not JSON. Branch on the status code first.
• Python client: transport failures raise AuthTransportError (3.0.0). The 2.x answer-shaped error dict is gone — an outage can never be misread as a denial. Catch the exception and map it to your unavailable/503 path, never to a permission denial. The old raise_on_error constructor argument is a deprecated no-op, so 2.x code keeps constructing.
• Reuse one key. A new key is a new empty namespace, not an error. Keep the key out of source control, logs, and URLs — it is the only thing protecting your data. Rotate it with POST /api/keys/rotate if it leaks.
• Per-user API keys (2.4.0): /api/apikeys/user/<user> (create/list), /api/apikeys/user/<user>/<key_id> (revoke), /api/apikeys/validate. auth mints rak_... secrets for your users, shows each exactly once, stores only a hash, and validates them inside your namespace — an identity UI fronts the lifecycle, backends validate then use the RBAC checks. Client methods: create_api_key, list_api_keys, revoke_api_key, validate_api_key, check_api_key_permission (validate + permission in one round trip), plus get_settings/set_strict_users. All of these also exist on the in-process Authorization wrapper for embedded consumers.
• Strict user identity is the default for NEW tenants (3.0.0). A tenant namespace created after 3.0.0 requires key-backed users for authorization decisions (user_not_key_backed answers; key-less membership grants answer 409) — create the user's API key first, then grant roles. Every tenant that existed before 3.0.0 was grandfathered with an explicit strict_users: false row (nothing changed for them at upgrade), and the audited per-tenant opt-out (PUT /api/settings {"strict_users": false}) survives indefinitely for validated machine-subject architectures. Details: docs/DEPRECATIONS.md.

Documentation

When to use — and not

Use it for RBAC: named roles, permissions, group membership, and boolean "can user X do Y" gates for a service, CLI, or workflow engine.

Not for authentication (login/passwords/sessions/OAuth/JWT), fine-grained / attribute-based rules (owner-of-this-record, time-of-day, row-level tenancy — reach for an ABAC/policy engine), or air-gapped hot loops where a network hop per check is too costly (cache, or use the library in-process).

Development

python3.11 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,ratelimit,migrations]"
make check   # ruff + mypy
make test    # sqlite suite
make test-postgres   # postgres integration (Docker), encryption on

See CONTRIBUTING.md for the full workflow. Licensed under the MIT License.