[TW-4608] feat(auth): add multi-credential support for authentication

[radenkovic]

Multi-Credential Feature Implementation

Overview

This document summarizes the implementation of the multi-credential authentication feature in the Nylas Node.js SDK. The multi-credential feature allows customers to maintain multiple different provider credential sets (client_id/client_secret combinations) under a single Connector.

What is Multi-Credential?

Multi-credential enables:

• Multiple GCP projects under one Google Connector
• Multiple Azure/Microsoft tenants under one Microsoft Connector
• Different credential sets for different use cases within the same provider

How It Works

1. Connector Creation: When creating a Connector with provider credentials, a "default" credential record is automatically created and associated with that Connector.

2. Additional Credentials: Create multiple credential records under the same Connector using the Credentials CRUD API, each representing a different client_id/client_secret combo.

3. Credential Selection During Authentication:

   • Custom Auth: Pass credentialId in the request body under settings
   • Hosted Auth: Pass credentialId as a query parameter (when response_type is "code")
   • If no credentialId is specified, the connector's default credential is used

Implementation Changes

1. Model Updates

src/models/connectors.ts

• Added activeCredentialId?: string to Connector interface
  • Represents the default credential used for authentication
• Added activeCredentialId?: string to UpdateConnectorRequest interface
  • Allows updating the default credential for a connector

src/models/grants.ts

• Added credentialId?: string to Grant interface
  • Links the grant to the specific credential used during authentication
• Updated CreateGrantRequest.settings to support credentialId
  • Allows specifying which credential to use for custom authentication

src/models/auth.ts

• Added credentialId?: string to URLForAuthenticationConfig interface
  • Enables specifying a credential for hosted OAuth authentication

2. Resource Updates

src/resources/auth.ts

• Updated urlAuthBuilder() method to include credential_id query parameter when provided
  • Supports multi-credential in both standard OAuth and PKCE flows

3. Test Coverage

tests/resources/auth.spec.ts

Added comprehensive tests for:

• Hosted OAuth with credentialId parameter
• PKCE flow with credentialId parameter
• Custom authentication with credentialId in settings
• Verification that credentialId is not added when not provided

Usage Examples

1. Create a Connector (Creates Default Credential)

const connector = await nylas.connectors.create({
  requestBody: {
    name: 'My Google Connector',
    provider: 'google',
    settings: {
      clientId: 'default-client-id',
      clientSecret: 'default-client-secret',
    },
  },
});

2. Create Additional Credentials

const credential2 = await nylas.connectors.credentials.create({
  provider: 'google',
  requestBody: {
    name: 'GCP Project 2',
    credentialType: CredentialType.CONNECTOR,
    credentialData: {
      clientId: 'project2-client-id',
      clientSecret: 'project2-client-secret',
    },
  },
});

3. Use Specific Credential in Hosted Auth

const authUrl = nylas.auth.urlForOAuth2({
  clientId: 'your-app-client-id',
  redirectUri: 'https://your-app.com/callback',
  provider: 'google',
  credentialId: credential2.data.id, // Use the second credential
});

4. Use Specific Credential in Hosted Auth with PKCE

const pkceAuth = nylas.auth.urlForOAuth2PKCE({
  clientId: 'your-app-client-id',
  redirectUri: 'https://your-app.com/callback',
  provider: 'google',
  credentialId: credential2.data.id, // Use the second credential
});

5. Use Specific Credential in Custom Auth

const grant = await nylas.auth.customAuthentication({
  requestBody: {
    provider: 'google',
    settings: {
      // ... other provider-specific settings
      credentialId: credential2.data.id, // Use the second credential
    },
  },
});

6. Update Connector's Default Credential

await nylas.connectors.update({
  provider: 'google',
  requestBody: {
    activeCredentialId: credential2.data.id,
  },
});

API Compatibility

Backward Compatibility

All changes are backward compatible:

• New fields are optional
• Existing code continues to work without modification
• When credentialId is not specified, the connector's default credential is used

Response Fields

Responses now include credential information:

• Grant objects include credentialId field
• Connector objects include activeCredentialId field

Testing

All tests pass successfully:

• ✅ 28 auth tests (including 5 new multi-credential tests)
• ✅ 365 total tests across the SDK
• ✅ 99.07% statement coverage
• ✅ No linter errors
• ✅ TypeScript compilation successful

Notes

• The Credentials CRUD API was already implemented in the SDK
• Admin consent flow already supported credentialId for Microsoft
• This implementation extends credential support to standard OAuth flows and custom authentication

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.61%. Comparing base (499670b) to head (bea22cb).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #713   +/-   ##
=======================================
  Coverage   98.60%   98.61%           
=======================================
  Files          35       35           
  Lines         791      793    +2     
  Branches       68       69    +1     
=======================================
+ Hits          780      782    +2     
  Misses         11       11           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.