API Reference

Pepy Hat API

Centralized authorization for your internal apps. Use authentik to authenticate users, then call Pepy Hat to fetch their roles and permissions for your app.

How it fits together

User clicks "Sign in" on your app → redirect to authentik (OIDC).
authentik authenticates the user and redirects back to your app's callback with an authorization code.
Your app exchanges the code for an ID token containing the user's email.
Your app calls GET /api/v1/authz/<email>?app=<your-slug> on Pepy Hat with your app's API key.
Your app receives the user's roles and permissions for your app, and uses them to gate access locally.

Authentication

Each app registered in Pepy Hat gets a unique API key. Send it on every request:

X-API-Key: phk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The current key is always viewable on the app's detail page under API key. Store it securely (env var, secret manager) and rotate via the same page if compromised.

Endpoint

GET /api/v1/authz/{email}?app={slug}

Returns the roles and permissions assigned to the given user for the given app.

Path parameters

The user's email (case-insensitive). The user must exist in Pepy Hat.

Query parameters

app	Your app's slug (must match the X-API-Key).

Headers

X-API-Key

Your app's API key.

Example request

curl -H "X-API-Key: phk_..." \
  "https://pepy-hat.example.com/api/v1/authz/[email protected]?app=crm"

Example response

{
  "email": "[email protected]",
  "app": "crm",
  "found": true,
  "active": true,
  "roles": ["admin", "viewer"],
  "permissions": ["users.read", "users.write"]
}

Field	Description
found	`false` if the user is not registered in Pepy Hat. Treat as no access.
active	`false` if the user has been deactivated. Treat as no access.
roles	Slugs of roles granted to this user for this app. Empty array if none.
permissions	Deduplicated union of permissions across all granted roles.

Errors

Status	Meaning
400	Missing `app` query parameter.
401	Missing `X-API-Key` header.
403	API key is invalid for this app.
404	App slug not registered in Pepy Hat.

An unknown user is not a 404 — the endpoint returns 200 with found: false and empty roles/permissions, so apps can deny access uniformly.

Go example

// after exchanging the OIDC code for an ID token, fetch authz
req, _ := http.NewRequest("GET",
    "https://pepy-hat.example.com/api/v1/authz/"+email+"?app=crm", nil)
req.Header.Set("X-API-Key", os.Getenv("PEPY_HAT_API_KEY"))

resp, err := http.DefaultClient.Do(req)
// ... handle err, decode JSON, gate routes by resp.Permissions