Login with PlanetGraph
Turn every sign-up and login into richer context for your product.
Instead of starting with a blank profile, your app can connect to a living graph of people where PlanetGraph records relationships for future insights.
How It Works
- Your app redirects the user to
https://planetgraph.ai/login_with?app_id=YOUR_APP_UUID&state=YOUR_STATE. - The user signs up or logs in using their preferred provider.
- PlanetGraph fetches all the information it has on the user, subject to access policies, and links your app to the user.
- PlanetGraph redirects back to your specified callback URL with rich information on the user.
You may use Login with PlanetGraph to augment your product's own user database or as a complete replacement.
Managing Apps
Create and review Login with PlanetGraph apps from the app dashboard. App definitions are graph nodes, so they can also be managed through the graph API.
apps My AppsApp Node Properties
| Property | Required | Description |
|---|---|---|
| name | Yes | Display name shown on the Login with PlanetGraph page. |
| description | No | Short app description shown to the user before login. |
| logo_url | No | URL for the app logo displayed on the login page. |
| auth_methods | No | Allowed methods such as email, Google, and GitHub. Defaults to all methods. |
| permissions | No | Requested data permissions for the app. |
| callback_url | Yes | URL on your server that reveis the login result |
Callback
After a successful login, PlanetGraph redirects the user's browser to your app's callback_url with an HTTP GET request. The callback data is sent as URL query parameters; no request body is sent.
If your callback URL already has query parameters, PlanetGraph preserves them and appends the login result parameters.
The optional state value is generated by your app before redirecting to PlanetGraph. PlanetGraph returns the same value in both the callback query string and signed token so your server can match the callback to the browser session that started the login.
| Query Parameter | Description |
|---|---|
| person_id | UUID of the PlanetGraph Person node for the authenticated user. |
| app_id | UUID of your 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 value supplied by your app and returned unchanged for callback/session matching. |
| login_token | Short-lived signed token your server should verify before trusting the callback. |
Security
Every callback includes a short-lived signed login_token. The token binds the Person ID, App ID, login ID, auth method, optional state, issue time, and expiration time to the callback so your server can confirm the login result came from PlanetGraph before trusting it.
Your callback handler should read the login_token and state from the callback query string, verify the token server-side, and confirm the returned state matches the browser session that initiated login before creating a session or updating local user data.
/api/v1/login-with/callback-token/verifySubmit the login_token to verify the signature and expiration, then use the verified payload returned by PlanetGraph.
Endpoints
/api/v1/login-with/apps/{app_id}Read public app metadata for the login page.
/api/v1/login-with/apps/{app_id}/completeComplete an authenticated login and return the callback redirect URL.
/api/v1/login-with/callback-token/verifyVerify a signed callback token before trusting the login result.
/api/v1/login-with/appsList apps owned by the current PlanetGraph account.
/api/v1/login-with/appsCreate an app node configured for Login with PlanetGraph.