PlanetGraph Login with PlanetGraph Guide

Purpose
Login with PlanetGraph 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-with-planetgraph

Core flow
1) The app redirects the user to:
   https://planetgraph.ai/login_with?app_id=YOUR_APP_UUID&state=YOUR_STATE
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 redirects the browser back to the app callback URL.

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
- callback_url: required URL on the app server that receives the login result

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.

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
- 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 Login with PlanetGraph

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