OAuth 2.0

Google OAuth details for PaySmart

PaySmart uses Google OAuth 2.0 for sign-in. We request only essential scopes, exchange short-lived authorization codes for tokens, and protect tokens on the backend. Use this page to configure your client, set redirect URIs, and validate the flow end-to-end.

View configuration Contact support
Provider: Google Flow: OAuth 2.0 auth code Scopes: openid email profile

Configuration at a glance

Minimal scopes and standard Google endpoints for production and staging.

Authorization request

Use your registered redirect URI in Google Cloud. Replace placeholders with your IDs.

GET https://accounts.google.com/o/oauth2/v2/auth
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.example.com/auth/google/callback
  &response_type=code
  &scope=openid email profile
  &access_type=offline
  &prompt=consent

Token exchange

Exchange the one-time code for tokens on a secure backend.

POST https://oauth2.googleapis.com/token
  client_id=YOUR_CLIENT_ID
  client_secret=YOUR_CLIENT_SECRET
  code=AUTH_CODE_FROM_REDIRECT
  grant_type=authorization_code
  redirect_uri=https://yourapp.example.com/auth/google/callback

User info request

Use the access token to fetch profile claims and attach to the user session.

GET https://openidconnect.googleapis.com/v1/userinfo
Authorization: Bearer ACCESS_TOKEN

Tip: For local development, add localhost redirect URIs (e.g., https://localhost:5173/auth/google/callback) to your Google OAuth client.

Integration steps

Follow these to keep the flow consistent across environments.

  1. Create or reuse a Google OAuth client. Set application type to Web, add your production and staging redirect URIs, and download the client ID/secret.
  2. Trigger the authorization request from your app. Send users to the Google authorization URL with state + PKCE if your client supports it. Always include a state token you verify on return.
  3. Exchange the code on the backend. Perform the code-for-token exchange server-side, then attach the resulting user identity to your session or JWT.
  4. Store tokens safely. Keep refresh tokens encrypted at rest, scope them to the smallest set needed, and rotate if compromised.
  5. Handle errors gracefully. Surface clear messages for invalid_grant, consent_required, or redirect_uri_mismatch errors and prompt the user to retry.

Security & privacy guardrails

Built to protect user identity and keep auditability intact.

Scope minimization

  • Default scopes: openid email profile. Request additional scopes only when required.
  • Use incremental authorization if you later add optional scopes.

Redirect safety

  • Always validate state on return and bind it to the initiating session.
  • Register every redirect URI explicitly; mismatches will be blocked by Google.

Token handling

  • Prefer short access token lifetimes; keep refresh tokens server-side only.
  • Log token usage for audits and rotate secrets on compromise.

Account linking

  • Use the subject (sub) and email claim to bind Google identities to PaySmart accounts.
  • Block account creation when email is unverified or domain is disallowed.

Testing checklist

Validate your integration before shipping.

Happy path

  • Login completes and user info is returned with expected claims.
  • Session is created and persisted after redirect.

Error handling

  • State mismatch redirects to a safe error screen.
  • Invalid or expired codes surface a retry with a fresh state.

Environments

  • Separate Google OAuth clients for prod vs. staging/local.
  • Each environment has its own redirect URIs and secrets.

Need help? Email voltservice@metalbrain.net or open a support ticket.