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: check success before reading data. On transport failure the client does not raise by default — it returns {"error", "success": False, "transport_error": True, "data": {...}} where data only echoes your inputs and does NOT contain the answer field (has_permission, count, ...). Reading data blindly turns an outage into a false "no". Pass Client(..., raise_on_error=True) to get an AuthTransportError exception instead of the error dict.
• 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.
• DEPRECATED — bare user strings. Asserting a <user> that no validated API key backs is scheduled for decommission: 2.5.0 adds opt-in per-tenant strict mode, 3.0.0 makes key-backed users mandatory (each phase ships only after every consuming platform confirms). Migrate backends to validate → user → has_permission now. 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.