Auth service

/auth is where every identity in Pantahub comes from: user registration, login for all three account classes (USER, DEVICE, SERVICE), token refresh, and the OAuth-inspired flows that let services and apps act on behalf of users. Concepts: Accounts, identity & tokens.

Register a user

Registration is a two-step flow: POST your details, then finish the challenge in the browser (captcha + email verification).

curl -s -X POST https://api.pantahub.com/auth/accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "you@example.com",
    "nick": "yournick",
    "password": "yourpassword"
  }'

If nick and email are free, the response carries a redirect-uri — open it in a browser to solve the captcha and trigger the verification email. (On a development deployment without a mail server, the verification link is printed on the server console.)

Log in

TOKEN=$(curl -s -X POST https://api.pantahub.com/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"yournick","password":"yourpassword"}' | jq -r .token)

The same endpoint serves all account classes — a device logs in with its PRN as username:

DTOKEN=$(curl -s -X POST https://api.pantahub.com/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"prn:::devices:/<device-id>","password":"<creds.secret>"}' \
  | jq -r .token)

To refresh a token before it expires, GET the same endpoint with the Bearer token:

curl -s https://api.pantahub.com/auth/login -H "Authorization: Bearer $TOKEN"

GET /auth/auth_status returns the claims of whatever token you present — handy to check what identity and scopes a token actually carries.

Service authorization (access codes)

Services authenticate like normal accounts, and can impersonate a user through a token exchange inspired by OAuth2: the user issues an access code scoped to the service, the service swaps it for a long-lived token.

# 1. user issues an authorization code for the service
CODE=$(curl -s -X POST https://api.pantahub.com/auth/code \
  -H "Authorization: Bearer $UTOKEN" -H 'Content-Type: application/json' \
  -d '{"service":"prn:pantahub.com:auth:/service1","scopes":"*"}' | jq -r .code)

# 2. service logs in as itself, then swaps the code for a delegated token
OTOK=$(curl -s -X POST https://api.pantahub.com/auth/token \
  -H "Authorization: Bearer $STOKEN" -H 'Content-Type: application/json' \
  -d "{\"access-code\":\"$CODE\"}" | jq -r .token)

The delegated token authenticates as the user, with aud set to the service and limited to the granted scopes. There is also an implicit-style /auth/authorize endpoint that issues an access token directly for a pre-registered client with a redirect URI (tokens expire after ~1 hour). Third-party applications register their scopes and redirect URIs through the apps service.

Admin abilities

Accounts listed in PANTAHUB_ADMINS (default: the admin demo account) can:

• List all accounts: GET /auth/accounts?asadmin=yes.
• Log in as another user with the special username youradmin==>targetuser and the admin's own password — useful for support work.

Endpoint reference

Each page in the API Reference documents the request/response schema and lets you try the call live:

Endpoint	Reference
POST /auth/accounts	Register account
POST /auth/login	Login
GET /auth/auth_status	Token claims
POST /auth/token/refresh	Refresh token
POST /auth/code	Issue access code
POST /auth/token	Swap code for token
POST /auth/authorize	Implicit authorize
GET /auth/accounts	List accounts (admin)
POST /auth/recover · POST /auth/password	Recover · Set password