Pi Apps Frontend Javascript SDK Documentation

Pi Sign-in uses the OAuth 2.0 implicit flow, which is a simplified flow designed for browser-based applications. It requires no backend exchange and no client secret.

The Flow:

1. Redirect: You redirect the user to the authorization server's /oauth/authorize endpoint with your client_id, redirect_uri, scope, and an optional state value.
2. Authentication: The user authenticates and approves your app within the Pi Browser.
3. Callback: The server redirects the browser back to your redirect_uri. The access token is appended to the URL fragment (the part after #), not as a query parameter.
4. Token Retrieval: Your front-end JavaScript reads the token from the fragment, verifies the state to prevent CSRF, and uses the token to call the Pi API.

Note: Currently, implicit flow is the only supported flow. You are issued a client_id only; there is no client_secret.

Payments in the Pi Platform are wrappers around blockchain transactions that synchronize your app, the Pi Blockchain, and Pi Servers. The process follows a three-phase lifecycle to ensure security and synchronization:

Phase I: Payment creation and Server-Side Approval

1. Creation: The app's frontend calls createPayment. The Payment Flow UI opens but is locked.
2. Approval Trigger: The JS SDK triggers onReadyForServerApproval and provides a PaymentID.
3. Server Communication: Your frontend must send this PaymentID to your backend server.
4. Approval: Your server calls the Pi Server /approve API. This unlocks the UI for the user.

Phase II: User interaction and blockchain transaction

• The user interacts with the Payment Flow UI to confirm, sign, and submit the transaction to the Pi Blockchain.
• This phase is handled entirely by the Pi Apps Platform and the Pi Wallet.
• Note: The payment flow remains open after submission until Phase III is complete.

Phase III: Server-Side Completion

1. Completion Trigger: The JS SDK triggers onReadyForServerCompletion and provides the blockchain transaction identifier (TxID).
2. Server Communication: Your frontend sends the TxID to your backend server.
3. Completion: Your server calls the Pi Server /complete API. This verifies the transaction and allows the payment flow UI to close.
4. Finalization: Once the flow closes, your app becomes visible again, and you can update your UI to show a confirmation screen.

A2U payments involve interacting with both the Pi Blockchain and the Pi backend.

• Pi Blockchain: Acts as the single source of truth for the actual exchange of Pi.
• Pi Backend: Used to enhance user experience and developer reliability. It provides understandable memos in the user's wallet, links back to your app, and helps prevent technical errors like double payments due to server faults.

Key Benefits

• User Privacy: Enables safe access to a user's wallet address only upon their consent and intent to receive Pi.
• Wallet Accuracy: The API returns the current user wallet if a change was necessary, preventing payments to deprecated or inaccessible addresses.
• Error Recovery: By informing the Pi backend before and after a blockchain transaction, you can recover metadata and transaction details if a technical issue prevents your local database from recording the event. This helps avoid accidental depletion of app wallets.
• Ecosystem Integration: Payments made via the A2U API appear in the user's wallet as coming from your specific app rather than an unknown address, allowing for future features like direct links back to your app or product thumbnails.

After authentication, the browser redirects to your redirect_uri with data in the URL fragment (#). You must parse this fragment in your front-end JavaScript.

Success Case

URL format: https://yourapp.com/callback#access_token=xxxxx&token_type=Bearer&expires_in=3600&state=abc123

Fragment Parameters:

• access_token: The bearer token.
• token_type: Always Bearer.
• expires_in: Lifetime in seconds.
• state: The echoed CSRF value. You must verify this matches the state you sent.

Failure Case

URL format: https://yourapp.com/callback#error=access_denied&state=abc123

Error Values:

• access_denied: User declined consent.
• expired: Request timed out.
• cancelled: User cancelled before approval.
• server_error: Unexpected server error.

Implementation Example

const params = new URLSearchParams(window.location.hash.slice(1));
const expectedState = sessionStorage.getItem("pi_oauth_state");
sessionStorage.removeItem("pi_oauth_state");

if (params.get("state") !== expectedState) {
  throw new Error("State mismatch — possible CSRF, aborting.");
}

const error = params.get("error");
if (error) {
  console.error("Pi Sign-in failed:", error);
} else {
  const accessToken = params.get("access_token");

  const me = await fetch("https://api.minepi.com/v2/me", {
    headers: { Authorization: `Bearer ${accessToken}` },
  }).then((r) => r.json());

  // Use me.uid to create your own session
}

// Clear the token from the URL history
history.replaceState(null, "", window.location.pathname);

const params = new URLSearchParams(window.location.hash.slice(1));
const expectedState = sessionStorage.getItem("pi_oauth_state");
sessionStorage.removeItem("pi_oauth_state");

if (params.get("state") !== expectedState) {
  throw new Error("State mismatch — possible CSRF, aborting.");
}

const error = params.get("error");
if (error) {
  // handle access_denied / expired / cancelled / server_error
  console.error("Pi Sign-in failed:", error);
} else {
  const accessToken = params.get("access_token");

  const me = await fetch("https://api.minepi.com/v2/me", {
    headers: { Authorization: `Bearer ${accessToken}` },
  }).then((r) => r.json());

  // me = { uid, username, ... } — create your own session keyed on me.uid
}

// Clear the token from the URL so it isn't left in history
history.replaceState(null, "", window.location.pathname);

Before integrating, you must complete these steps in the Pi Developer Portal:

1. Verify your app domain

Pi Sign-in only redirects to domains you own.

• Set Your App's URL (e.g., https://yourapp.com) in the Configuration page.
• Complete domain verification by placing the provided validation key in a file at https://yourapp.com/validation-key.txt and clicking Verify Domain.
• Note: Until verified, you can only use loopback redirect URIs (e.g., localhost) for local development.

2. Enable Pi Sign-in

• Navigate to the Pi Sign-in section of your app.
• Toggle Enabled to ON.
• Copy your OAuth Client ID (this is public; there is no client secret).

3. Register your redirect URIs

• Add your callback URIs under Redirect URIs (one per line).
• Production URIs must use https:// and must belong to your verified domain.
• Loopback hosts (localhost, 127.0.0.1, [::1]) are always allowed and can use http://.