Skip to content

Connect an app

Register your app at every deploy with a connect token - the API call, the answer, the Python helper and the Django integration.

An app needs two values at deploy: REM Auth's address and one connect token. It registers itself; nobody clicks anything.

1. Get a connect token

A super admin makes one under Admin > Connect tokens, scoped to product slugs (*, rch-*, payments), optionally expiring. It is shown once (rat_...). Keep it in your deployment secrets as REMAUTH_REGISTRATION_TOKEN.

2. Register at every start (idempotent)

POST https://auth.remplatforms.com/api/products/register
Authorization: Bearer rat_...
Content-Type: application/json

{"slug": "yourapp", "name": "Your App",
 "home_url": "https://yourapp.com/",
 "redirect_uris": ["https://yourapp.com/api/auth/oidc/callback"],
 "groups": ["REM Staff"],
 "signin_mode": "redirect",
 "webhook_url": "https://yourapp.com/api/rem-auth-webhook",
 "roles": ["admin", "member"],
 "health_url": "https://yourapp.com/healthz",
 "brand": {"short": "App", "mark": "YA", "support_email": "support@remplatforms.com"}}

201 (created) or 200 (updated) with client_id, client_secret, issuer, discovery_url, authorize_url, token_url, userinfo_url, introspect_url, revoke_url, jwks_url, end_session_url, signout_url, my_apps_url, scopes, status, roles, and webhook_secret when you sent a webhook_url. The same call twice changes nothing and returns the same client.

It creates or updates the OIDC client (confidential; code, refresh and client-credentials grants), the application, the callback and after-sign-out addresses, the brand, and who may sign in (the listed groups plus REM Super Admins; none listed = every signed-in person). Errors: 401 (no, revoked or expired token), 403 (the token does not cover the slug), 400 (a field, said plainly).

Stay "online" in the admin: register, send POST /api/products/heartbeat (HTTP Basic with client id and secret), exchange tokens, or answer your health address.

The Python helper

REMAUTH_URL=https://auth.remplatforms.com REMAUTH_REGISTRATION_TOKEN=rat_... \
  python remauth_register.py --slug yourapp --name "Your App" --mark YA \
    --home https://yourapp.com/ --redirect https://yourapp.com/api/auth/oidc/callback \
    --group "REM Staff" --health https://yourapp.com/healthz --env-out .remauth.env

It writes REMAUTH_ISSUER, REMAUTH_CLIENT_ID, REMAUTH_CLIENT_SECRET and REMAUTH_SIGNOUT_URL to the env file. Standard library only, safe on every start.

Django apps

remauth_django.py is registration, both sign-in modes, sign-out and webhooks in one file (REM Payments uses it):

# settings.py
REMAUTH_URL = env("REMAUTH_URL"); REMAUTH_REGISTRATION_TOKEN = env("REMAUTH_REGISTRATION_TOKEN")
REMAUTH_PUBLIC_URL = "https://yourapp.com"
REMAUTH_PRODUCT = {"slug": "yourapp", "name": "Your App", "home_url": REMAUTH_PUBLIC_URL + "/",
                   "redirect_uris": [REMAUTH_PUBLIC_URL + "/api/auth/oidc/callback", REMAUTH_PUBLIC_URL + "/api/rem-auth/callback"],
                   "webhook_url": REMAUTH_PUBLIC_URL + "/api/rem-auth-webhook", "roles": ["admin", "finance", "viewer"],
                   "groups": ["Accounts"]}
REMAUTH_USER_HANDLER = "myapp.auth.upsert_user"        # claims -> your user (default links safely)
REMAUTH_WEBHOOK_HANDLER = "myapp.auth.on_remauth_event"

# urls.py
import remauth_django
urlpatterns = [*remauth_django.urls(), ...]   # api/auth/oidc/start|callback, api/rem-auth/<path>, api/rem-auth-webhook

# logout view
return JsonResponse({"ok": True, "signout_url": remauth_django.sign_out(request)})

The login page sends people to /api/auth/oidc/start?next=/ (redirect mode) or renders the SDK's SignInForm against /api/rem-auth (in-app mode); remauth_django.mode() says which, as chosen in the admin. The default user handler links by sub (add a remauth_sub field to your user model), by e-mail only when verified, never re-links, and refuses unverified sign-ins.

The visitor's address

For lock-out and the audit log, your server reports the visitor's IP. Never take the leftmost X-Forwarded-For entry: the visitor writes it. Set the number of proxies you run in front of the app (REMAUTH_TRUSTED_PROXY_HOPS in Django, trustedProxyHops in the SDK).

Last updated 18 Nov 2026

Connect an app · REM Platforms Blog