PlanetGraph Login+ Guide

Purpose
PlanetGraph Login+ lets third-party apps route sign-up and login through PlanetGraph, then receive graph-backed user context after authentication.

Human documentation
- https://planetgraph.com/docs/login-plus

Quick start paths
1) Client-side JavaScript: load the hosted widget script at https://planetgraph.ai/widgets/login-plus.js. The widget renders a PlanetGraph sign-in button and opens a PlanetGraph-hosted popup.
2) Hosted Redirect: send the user to https://planetgraph.ai/login_with?app_id=YOUR_APP_UUID&state=YOUR_STATE. PlanetGraph hosts the login page and redirects back to the app callback URL configured for redirect flows.

Shared flow
1) The user starts from the client-side JavaScript widget or hosted redirect URL.
2) The user signs up or logs in using their preferred provider.
3) PlanetGraph fetches information it has on the user, subject to access policies, and links the app to the user.
4) PlanetGraph returns the signed login result by callback redirect or web_message postMessage, depending on result_mode.

App node
- The app is represented by a PlanetGraph app node.
- The app node UUID is the app_id.
- App definitions are graph nodes, so they can also be managed through the graph API.

App node properties
- name: required display name
- description: optional app description
- logo_url: optional app logo URL
- auth_methods: optional allowed methods such as email, Google, and GitHub; defaults to all methods
- permissions: optional requested permissions
- allowed_origins: optional browser origins allowed to start client-side JavaScript and web_message flows
- callback_url: optional URL on the app server; required only for hosted redirect or callback result mode

Quick Start: Client-Side JavaScript
- The hosted script is available at /widgets/login-plus.js.
- The simple script tag reads data-app-id, data-button-text, data-result-mode, and data-allowed-origins attributes.
- The explicit API is PlanetGraphLogin.mount(target, options).
- The widget opens /login_with with app_id, state, result_mode, and parent_origin query parameters.
- result_mode defaults to callback.
- result_mode=web_message posts the signed login result back to the opener window.
- web_message mode does not require callback_url, but it does require parent_origin to match an app allowed_origins entry.

Quick Start: Hosted Redirect
- Send users to /login_with?app_id=YOUR_APP_UUID&state=YOUR_STATE.
- This is the simplest backend-oriented integration.
- The app must configure callback_url for this flow.
- PlanetGraph redirects to the app callback_url with the signed login result as query parameters.
- The app backend should verify login_token and match state before creating a local session.

Callback contract
- PlanetGraph redirects to callback_url with an HTTP GET request.
- Callback values are URL query parameters.
- No request body is sent.
- If callback_url already has query parameters, PlanetGraph preserves them and appends login result parameters.

Callback query parameters
- person_id: UUID of the PlanetGraph Person node for the authenticated user
- app_id: UUID of the PlanetGraph app node
- login_id: UUID of the logged_into edge for this login event
- auth_method: authentication method used for this login
- state: optional app-supplied value returned unchanged for callback/session matching
- login_token: short-lived signed token the app server should verify before trusting the callback

Security guidance
- Treat app IDs as public identifiers.
- Generate a state value before redirecting the user to PlanetGraph.
- Store state in the app's own browser/session flow.
- On callback, verify login_token server-side.
- Confirm the returned state matches the app session that initiated login.
- Only create or update local user sessions after token and state validation succeeds.
- Only use web_message for client-side personalization, prototypes, or flows that forward login_token to the app backend for verification.
- Do not create privileged or durable sessions solely from browser-delivered web_message data.

Relevant API endpoints
- GET /api/v1/login-with/apps/{app_id}: read public app metadata for the login page
- POST /api/v1/login-with/apps/{app_id}/complete: complete an authenticated login and return callback redirect data or web_message payload data
- POST /api/v1/login-with/callback-token/verify: verify signed callback token
- GET /api/v1/login-with/apps: list apps owned by the authenticated PlanetGraph account
- POST /api/v1/login-with/apps: create an app node configured for PlanetGraph Login+

Terminology
- uses_app edge: persistent relationship between Person and App tracking first/last login
- logged_into edge: event relationship for one login with time and auth method
- login_token: signed callback token containing person_id, app_id, login_id, auth_method, optional state, issued-at, and expiration claims