Ppoppo Docs

Quickstart

By the end of this guide you'll have a user signed in with Ppoppo and their ppnum_id in hand. This is the short path; each step links to the full recipe when you need more.

1. Register your app

Register to get a login client client_id. Provide your app name, redirect URI(s), and the scopes you need (openid profile to start). To request credentials, contact partnership@ppoppo.com.

The login client has no client_secret — it uses PKCE. (Sending messages later uses a separate External API client; you don't need it for sign-in. See What is Ppoppo?.)

2. Configure your environment

PPOPPO_CLIENT_ID=yourapp_login_client
PPOPPO_AUTH_URL=https://accounts.ppoppo.com

3. Send the user to sign in

Generate a PKCE pair and redirect to the authorization endpoint:

https://accounts.ppoppo.com/oauth/authorize
  ?client_id=yourapp_login_client
  &redirect_uri=https://yourapp.com/auth/callback
  &response_type=code&scope=openid%20profile
  &state=RANDOM&code_challenge=CHALLENGE&code_challenge_method=S256

The full PKCE recipe is in the OAuth2 PKCE guide.

4. Exchange the code for tokens

When Ppoppo redirects back with code, exchange it from your server:

POST /oauth/token
grant_type=authorization_code&code=AUTH_CODE
&redirect_uri=https://yourapp.com/auth/callback
&client_id=yourapp_login_client&code_verifier=YOUR_VERIFIER

You get an access_token (1 hour) and a refresh_token (180-day inactivity).

5. Make an authenticated call

GET /oauth/userinfo
Authorization: Bearer <access_token>

The response's sub is the user's ppnum_id — your stable key. Store it (see User mapping). That's a complete sign-in.

Next steps