Skip to main content
After a user completes (or exits) the consent flow, they’re redirected to your redirect_uri with query parameters indicating the result.

Callback parameters

Do not ask end-users for uid or collect it in the frontend. Store the callback uid server-side and map it to your internal user record. This avoids wrong-user data access and keeps identifiers private.

Status values

success

First-time consent granted. This user has connected their data for the first time with your application.

reauthorized

User re-linked an existing consent. This happens when:
  • User clicks the link again after previously consenting
  • User re-authenticates after token expiration

failure

User cancelled or an error occurred during the flow.

Error codes

Handling callbacks

State verification

Always verify the state parameter matches what you stored before the redirect. This prevents CSRF attacks where an attacker tricks a user into linking their account to the attacker’s data.

What happens after success

When you receive success or reauthorized:
  1. Data export starts automatically - Emerge begins exporting the user’s data from their provider
  2. Export takes 1-15 minutes - Depending on data volume
  3. Webhook updates (optional) - You may receive consent events plus data.ready/data.failed for provider-level export updates
  4. Poll export readiness (recommended fallback) - Check GET /export/status/{uid} and query only when the provider in sources[] has data_ready: true
Use provider-level readiness from sources[] instead of assuming all providers are ready at once.

Completed session handling

If a user clicks a consent link after they’ve already completed consent:
  • They see a brief “already connected” message
  • They’re redirected to the Data Wallet (not back to your redirect_uri)
  • No new callback is triggered
This prevents confusion from re-processing completed flows.