Authentication

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

auth: {
  type: 'bearer_token',

  // Keys that must NEVER be sent to the frontend
  sensitiveKeys: ['accessToken'],

  // Default credential values (empty = user must provide)
  config: {
    accessToken: '',
  },

  // Verify the token works by calling a "who am I" endpoint
  userDetails: {
    url: 'https://api.example.com/users/me',
    method: 'GET',
    headers: {
      Authorization: 'Bearer [[accessToken]]',
      'Content-Type': 'application/json',
    },
    bodyType: 'json',
    body: {},
    mapping: {
      uid: '$.user.id',        // Unique user identifier → metadata
      name: '$.user.name',     // Display name → metadata
    },
  },
}

auth: {
  type: 'oauth2',

  sensitiveKeys: ['accessToken', 'refreshToken'],

  // OAuth configuration (available as {{key}} placeholders)
  config: {
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    scope: 'read write',
    response_type: 'code',
    grant_type: 'authorization_code',
    accessToken: '',
    refreshToken: '',
  },

  // Build the authorization redirect URL
  auth_url: {
    url: 'https://provider.com/oauth/authorize?client_id={{client_id}}&scope={{scope}}&response_type={{response_type}}&redirect_uri={{redirect_uri}}',
    method: 'GET',
    headers: {},
    bodyType: 'json',
    body: {},
    mapping: {},
  },

  // Exchange authorization code for tokens
  get_token: {
    url: 'https://provider.com/oauth/token',
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    bodyType: 'json',
    body: {
      client_id: '{{client_id}}',
      client_secret: '{{client_secret}}',
      grant_type: '{{grant_type}}',
      code: '{{code}}',
      redirect_uri: '{{redirect_uri}}',
    },
    // Map response to credential keys
    mapping: {
      accessToken: '$.access_token',
      refreshToken: '$.refresh_token',
      expiresIn: '$.expires_in',
    },
  },

  // Refresh expired tokens
  refresh_token: {
    url: 'https://provider.com/oauth/token',
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    bodyType: 'json',
    body: {
      client_id: '{{client_id}}',
      client_secret: '{{client_secret}}',
      grant_type: 'refresh_token',
      refresh_token: '[[refreshToken]]',
    },
    mapping: {
      accessToken: '$.access_token',
      refreshToken: '$.refresh_token',
      expiresIn: '$.expires_in',
    },
  },

  // Auto-refresh on 401 responses
  auto_refresh: true,

  // Fetch user identity after authentication
  userDetails: {
    url: 'https://api.provider.com/v2/oauth2/user/info',
    method: 'GET',
    headers: {
      Authorization: 'Bearer [[accessToken]]',
      'Content-Type': 'application/json',
    },
    bodyType: 'json',
    body: {},
    mapping: {
      uid: '$.data.id',
      name: '$.data.name',
    },
  },

  // Post-auth setup (see §4.4)
  registrationRequests: [],
}

User clicks "Connect" in Marketplace
        │
        ▼
┌─────────────────────┐
│ Browser popup opens  │
│ GET /:appNs/oauth2   │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Platform builds      │
│ auth_url & redirects │
│ to provider          │
└────────┬────────────┘
         │ User authorizes
         ▼
┌─────────────────────┐
│ Provider redirects   │
│ back with ?code=xxx  │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Platform executes    │
│ get_token request    │
│ (code → tokens)      │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Platform executes    │
│ userDetails request  │
│ (extract uid, name)  │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Tokens stored in     │
│ credentials;         │
│ userDetails → metadata │
│ registrationRequests   │
│ executed (if any)      │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Popup closes, main   │
│ window refreshes     │
└─────────────────────┘

auth: {
  // ...auth config...

  registrationRequests: [
    // Register your webhook URL with the provider
    {
      url: 'https://api.provider.com/webhooks',
      method: 'POST',
      headers: {
        Authorization: 'Bearer [[accessToken]]',
        'Content-Type': 'application/json',
      },
      bodyType: 'json',
      body: {
        url: '{{webhookUrl}}',     // Auto-injected: your webhook endpoint
        events: ['order.created', 'customer.updated'],
        secret: '{{webhookSecret}}',
      },
      mapping: {
        webhookId: '$.id',  // Saved to credentials for later reference
      },
    },

    // Prefer auth.userDetails for store profile; use registrationRequests
    // only for one-off setup outputs like webhook IDs.
    {
      url: 'https://api.provider.com/webhooks/subscribe',
      method: 'POST',
      headers: {
        Authorization: 'Bearer [[accessToken]]',
        'Store-Id': '[[storeId]]',   // Resolved from metadata
      },
      bodyType: 'json',
      body: {
        url: '{{webhookUrl}}',
      },
      mapping: {
        webhookSubscriptionId: '$.id',
      },
    },
  ],
}