Log in with Palloo

What it is

Palloo is an OpenID Connect provider. A website sends the visitor to Palloo, the visitor approves, and the website learns who they are: their Palloo user ID and, if they agree, their username, display name, avatar and email address. Any standard OpenID Connect library works.

The access tokens it hands out only open the userinfo endpoint. They cannot call the rest of the API, read messages or act for the person. To act inside servers, build a bot instead.

Log in with Palloo is switched on per instance. While it is off, every endpoint below answers 404 oidc_disabled, and GET /instance reports oidc_enabled: false.

Registering an app

There is no self-service registration and no dynamic client registration. Every app is reviewed by the Palloo team before it gets a client ID. App requests are opening gradually: if you don't see My apps in the Help center yet, open a general request there and tell us about your app. To request one:

1. Read the Developer Terms of Service. Your app must follow them.
2. Log in to the Help center with your Palloo account, open My apps and choose Request an app.
3. Tell us:
   • the app's name, as people will see it on the consent screen, and what it does,
   • its homepage and privacy policy (required), and its terms of service if it has them,
   • its redirect URIs, which must match byte for byte, use https and have no wildcard and no fragment. localhost and other loopback addresses (plain http allowed) are only accepted for an app marked for development; request a separate app for production,
   • the post-logout redirect URIs, if you use logout,
   • the scopes it needs (see below); ask only for what it uses,
   • how it authenticates (see below), and optionally a logo and the ID token signing algorithm (RS256 unless you pick ES256),
   • a contact email.
4. Accept the Developer Terms and send the request. We record which version you accepted.

We email your verified Palloo address when the request moves on. While it is in review you can edit or withdraw it. If we ask for changes, the request page shows what to fix and you send it back from there; you can also reply in the request's conversation. Once the app is registered, the request page shows the client ID and setup steps.

How your app authenticates

Every app is a confidential client: it must authenticate at the token endpoint, so the code exchange belongs on your server, never in a browser or mobile app. Apps without a server (public clients) are not supported yet.

• private_key_jwt (recommended). Paste your public key set (a JWK set, or one public JWK) into the request: RSA of at least 2048 bits, P-256 or Ed25519, at most 5 keys, each with a kid when there are several. Keep the private key on your server. No secret is ever sent to you, so nothing can leak on the way. Each client assertion must have your client ID as iss and sub, the issuer (https://app.palloo.app) as its only aud, expire within 5 minutes and carry a fresh jti.
• client_secret_basic. We issue a palloo_ocs_ secret. After the app is registered, you reveal it once on the request page, within a few days; we never send it by email, and the request page deletes its stored copy when you reveal it (encrypted database backups keep the old record until they expire). The Palloo team sees the secret once, when Palloo issues it. If you lose it, request a change and ask for a new secret.

Changing or deleting an app

Open the app under My apps. Request a change to update the redirect URIs, scopes, keys, name or other details, or to get a new client secret; the app keeps working with its current settings until we apply the change. The authentication method can't change; request a new app to switch. Delete this app asks us to remove it. We delete it in Palloo by hand and email you when it's done; from then on, sign-ins through it stop working.

Endpoints

These endpoints live on the issuer, https://app.palloo.app, not on the API address (https://api.palloo.app/v1). Everything is in the discovery document:

https://app.palloo.app/.well-known/openid-configuration

Scopes and claims

palloo:staff and palloo:admin are reserved for Palloo's own staff sites. An app can only ask for the scopes it was registered with; anything else is invalid_scope.

The ID token carries only iss, aud, sub, iat, exp, auth_time, amr, acr, sid, at_hash and nonce. The profile and email claims are only returned by the userinfo endpoint, so call it with the access token after the code exchange (most libraries do when asked to fetch user info).

The flow

Only the authorization code flow with PKCE is supported: response_type=code, response_mode=query, and a S256 code challenge. There is no implicit or hybrid flow, no password grant and no client credentials grant.

1. Send the visitor to Palloo

https://app.palloo.app/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback
  &scope=openid%20profile%20email
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

state and nonce are required (1 to 512 characters each). Optional: prompt (none, login or consent), max_age, and acr_values (urn:palloo:acr:mfa to require a second factor, urn:palloo:acr:pwd to accept a password alone).

Palloo shows its consent page, signs the visitor in if needed, and redirects back to your redirect_uri with code, state and iss. Check that state is yours and iss is https://app.palloo.app. Errors come back the same way, as error with state and iss, except an unknown client or an unregistered redirect URI, which never redirects anywhere.

2. Exchange the code

Within 60 seconds, from your server:

curl -sS -X POST https://app.palloo.app/api/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://example.com/auth/callback \
  -d code_verifier="$CODE_VERIFIER"

The answer holds access_token, token_type, expires_in, refresh_token, id_token and scope. Verify the ID token's signature with the key set (RS256 unless your app was registered for ES256), its iss, aud, exp and nonce.

3. Read who signed in

curl -sS https://app.palloo.app/api/v1/oauth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "sub": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "preferred_username": "alice",
  "name": "Alice",
  "email": "[email protected]",
  "email_verified": true
}

Use sub as the account key. Usernames and emails can change.

Tokens and sessions

• Refresh with grant_type=refresh_token. Each refresh token works once; presenting a used one ends the whole sign-in. Never refresh the same token twice in parallel.
• A sign-in ends when the person logs out of the Palloo session that approved it, when they revoke your app under Settings, Authorized Apps, when their account is suspended or deleted, and at the latest 30 days after it started.
• To log out, post id_token_hint (and optionally post_logout_redirect_uri and state) to the logout endpoint. Use the POST form so the ID token stays out of browser history. It ends your app's sign-in, not the person's Palloo session.
• The token, userinfo and revocation endpoints answer errors in the OAuth shape: {"error": "invalid_grant", "error_description": "..."}.

Limits

The token and revocation endpoints take 600 requests at once per app, then 20 a second. Userinfo takes 60 at once per access token, then 1 a second. Failed client authentications and invalid access tokens count against a per-address limit of 60, then 1 every 2 seconds.