Connecting Users

Nexus uses a secure, link-based OAuth connect flow to establish provider connections for your users. Your backend creates a one-time launch link, your user opens it in a browser, approves the provider, and data starts flowing.

Overview

The connect flow is designed so that:

• Your backend never handles OAuth tokens — Nexus manages them.
• The user’s browser session is short-lived and single-use.
• PKCE is supported for providers that require it (e.g., Fitbit).
• Your user is redirected back to your app with a success or error status.

Flow

1. Create a connect link

   Your backend calls Nexus API with the user’s identity and a redirect URI:

   curl -X POST https://nexus.example/api/connect-links \
     -H "Content-Type: application/json" \
     -d '{
       "apiKey": "your-tenant-api-key",
       "externalUserRef": "your-user-id-123",
       "redirectUri": "https://yourapp.com/connect/result"
     }'

   Response:

   {
     "launchUrl": "https://nexus.example/api/connect/launch?token=abc123...",
     "expiresAt": "2026-03-20T01:00:00.000Z"
   }

   The launchUrl is a one-time link. It expires after a short window.

2. User opens the launch URL

   Redirect your user’s browser to the launchUrl. Nexus:

   • Validates the one-time token.
   • Sets a secure, HttpOnly browser session cookie.
   • Redirects to the connect UI where the user picks a provider.

3. User selects a provider

   The connect UI shows available providers (e.g., Fitbit, Garmin, Oura). Your tenant’s privacy policy URL is displayed for transparency.

   Behind the scenes, Nexus:

   • Creates a pending connection attempt with an OAuth state token.
   • For PKCE providers, generates a code_verifier server-side (never exposed to the browser).
   • Returns the provider’s authorization URL.

4. User approves on the provider

   The user is redirected to the provider’s OAuth consent screen (e.g., Fitbit’s “Allow access to your data” page). After approval, the provider redirects back to Nexus’s callback endpoint.

5. Nexus completes the connection

   The callback handler:

   • Verifies the OAuth state token.
   • Exchanges the authorization code for tokens (with PKCE code_verifier if applicable).
   • Encrypts and stores the tokens.
   • Creates or updates the connection and binds it to your user.
   • Redirects the user to your redirectUri with a status parameter.

   Success redirect:

   https://yourapp.com/connect/result?status=ok

   Error redirect:

   https://yourapp.com/connect/result?status=error

Key Concepts

External User Ref

The externalUserRef is your user identifier — whatever ID you use in your system. Nexus maps it to an internal tenant_user_id, and outbound webhooks echo your value as external_user_ref alongside the internal user_id.

Connections vs Bindings

• A connection is a link between Nexus and a provider account (e.g., “Fitbit user ABC”).
• A binding ties a connection to one of your users within your tenant.
• One provider connection can be bound to multiple users (rare but supported).

Shared Connections

If a provider user has already connected via another tenant, Nexus reuses the same connection. Your user gets a new binding to the existing connection. Token management is shared — Nexus handles refresh and revocation centrally.

After Connection

Once connected, data flows automatically:

1. The provider sends change notifications to Nexus.
2. Nexus fetches the updated data using the stored OAuth tokens.
3. Data is normalized into the canonical event format.
4. Events are delivered to your webhook subscriptions.

Tip

You don’t need to poll for data. Nexus pushes events to your webhook endpoints as they arrive from the provider.

Subscribing to Events

Before data can be delivered, register a webhook subscription for the event types you want:

curl -X POST https://nexus.example/api/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-tenant-api-key" \
  -d '{
    "tenantId": "your-tenant-id",
    "eventType": "daily_summary",
    "endpointUrl": "https://yourapp.com/webhooks/fitness"
  }'

You can subscribe to any event type — one subscription per event type per endpoint.

Stopping Delivery

To stop receiving a given event type, remove the webhook subscription:

curl -X DELETE https://nexus.example/api/admin/subscriptions/subscription-uuid \
  -H "CF-Access-JWT-Assertion: <access-jwt>"

This disables event delivery for that subscription.

Error Handling

Scenario	Behavior
Launch token expired or reused	403 on launch, user must request a new link.
User cancels on provider	Redirected to your redirectUri with status=error.
Token exchange fails	Redirected with status=error. Connection attempt marked failed.
Provider connection already exists	Reused. New binding created for your user.