PocketID — Reference

Links

• GitHub: https://github.com/stonith404/pocket-id
• Docs: https://stonith404.github.io/pocket-id/
• OIDC Discovery: https://auth.eva-00.network/.well-known/openid-configuration

Authentication

API requests use an API key passed via the X-API-Key header. The API key is stored in Vault at secret/pocketid → api_key.

curl -s -H "X-API-Key: $POCKETID_API_KEY" \
  https://auth.eva-00.network/api/...

API — OIDC Clients

List all clients

curl -s -H "X-API-Key: $POCKETID_API_KEY" \
  https://auth.eva-00.network/api/oidc/clients | python3 -c \
  "import json,sys; [print(f'{c[\"id\"]} {c[\"name\"]} callback={c.get(\"callbackURLs\",[])}') for c in json.load(sys.stdin)]"

Create a client

curl -s -X POST -H "Authorization: Bearer $POCKETID_API_KEY" \
  -H "Content-Type: application/json" \
  https://auth.eva-00.network/api/oidc/clients \
  -d '{"name": "my-service", "callbackURLs": ["https://my-service.eva-00.network/callback"]}'

Generate client secret

curl -s -X POST -H "Authorization: Bearer $POCKETID_API_KEY" \
  https://auth.eva-00.network/api/oidc/clients/<client-id>/secret

Update a client

curl -s -X PUT -H "Authorization: Bearer $POCKETID_API_KEY" \
  -H "Content-Type: application/json" \
  https://auth.eva-00.network/api/oidc/clients/<client-id> \
  -d '{"name": "my-service", "callbackURLs": ["https://my-service.eva-00.network/callback"], "isGroupRestricted": true}'

Delete a client

curl -s -X DELETE -H "Authorization: Bearer $POCKETID_API_KEY" \
  https://auth.eva-00.network/api/oidc/clients/<client-id>

API — Users

List users

curl -s -H "X-API-Key: $POCKETID_API_KEY" \
  https://auth.eva-00.network/api/users | python3 -c \
  "import json,sys; [print(f'{u[\"id\"]} {u[\"username\"]} admin={u[\"isAdmin\"]}') for u in json.load(sys.stdin)]"

Create a user

curl -s -X POST -H "Authorization: Bearer $POCKETID_API_KEY" \
  -H "Content-Type: application/json" \
  https://auth.eva-00.network/api/users \
  -d '{"username": "newuser", "email": "[email protected]", "isAdmin": false}'

Update a user

Important: PUT requires the full user object, not a partial update. Missing fields will be reset.

curl -s -X PUT -H "Authorization: Bearer $POCKETID_API_KEY" \
  -H "Content-Type: application/json" \
  https://auth.eva-00.network/api/users/<user-id> \
  -d '{"username": "newuser", "email": "[email protected]", "isAdmin": false, "emailVerified": true}'

Note: emailVerified must be true or OIDC logins will fail for that user.

Delete a user

curl -s -X DELETE -H "Authorization: Bearer $POCKETID_API_KEY" \
  https://auth.eva-00.network/api/users/<user-id>

API — User Groups

List groups

curl -s -H "X-API-Key: $POCKETID_API_KEY" \
  https://auth.eva-00.network/api/user-groups | python3 -c \
  "import json,sys; [print(f'{g[\"id\"]} {g[\"name\"]} friendly={g.get(\"friendlyName\",\"\")}') for g in json.load(sys.stdin)]"

Create a group

curl -s -X POST -H "Authorization: Bearer $POCKETID_API_KEY" \
  -H "Content-Type: application/json" \
  https://auth.eva-00.network/api/user-groups \
  -d '{"name": "my-group", "friendlyName": "My Group"}'

Set group members

curl -s -X PUT -H "Authorization: Bearer $POCKETID_API_KEY" \
  -H "Content-Type: application/json" \
  https://auth.eva-00.network/api/user-groups/<group-id>/users \
  -d '{"userIds": ["<user-id-1>", "<user-id-2>"]}'

Set allowed OIDC clients for a group

curl -s -X PUT -H "Authorization: Bearer $POCKETID_API_KEY" \
  -H "Content-Type: application/json" \
  https://auth.eva-00.network/api/user-groups/<group-id>/allowed-oidc-clients \
  -d '{"oidcClientIds": ["<client-id-1>", "<client-id-2>"]}'

API — Application Configuration

Get app config

curl -s -H "X-API-Key: $POCKETID_API_KEY" \
  https://auth.eva-00.network/api/application-configuration

Update app config

curl -s -X PUT -H "Authorization: Bearer $POCKETID_API_KEY" \
  -H "Content-Type: application/json" \
  https://auth.eva-00.network/api/application-configuration \
  -d '{"appName": "PocketID", "emailEnabled": false}'

OIDC Standard Endpoints

Endpoint	URL
Discovery	https://auth.eva-00.network/.well-known/openid-configuration
Authorization	https://auth.eva-00.network/authorize
Token	https://auth.eva-00.network/api/oidc/token
Userinfo	https://auth.eva-00.network/api/oidc/userinfo
JWKS	https://auth.eva-00.network/api/oidc/jwks

What the API/CLI Cannot Do

Gap	Workaround
Cannot manage passkeys (WebAuthn credentials) via API	Users register passkeys via the web UI on their device
Cannot read client secrets after creation (returned once)	Regenerate via POST /api/oidc/clients/{id}/secret
No CLI tool	API-only; use curl for automation
Cannot manage audit logs via API	View in the web UI: Settings → Audit Logs
PUT /api/users requires full object (not partial)	Always read the user first, merge changes, then PUT the full object
emailVerified must be manually set to true	Include "emailVerified": true in user creation/update or OIDC logins fail
Cannot customize the login page branding via API	Use environment variables (PUBLIC_APP_NAME, etc.) in docker-compose
No built-in Prometheus metrics	Use Loki logs for observability