Using multiple provider applications

Nylas supports using multiple provider auth applications (credentials) with a single connector. This allows you to authenticate users with different provider applications while maintaining a single connector per provider in your Nylas application.

When to use multiple provider applications

Use multiple provider applications when you need to authenticate users with different provider auth apps under the same connector. Common use cases include:

• Enterprise customers who own their provider applications: Some enterprise customers have security or compliance requirements that require them to own and control their provider applications (for example, their own Google Cloud Platform project or Azure app). They can’t use your application’s provider app, but you can still authenticate them by creating a credential using their provider application credentials.

• Separate provider applications per environment: You might want to use different provider applications for development, staging, and production environments while maintaining a single connector.

• Customer-specific provider applications: If different customers require their own provider applications, you can create separate credentials for each customer’s provider app and authenticate users with the appropriate credential.

Understanding connectors and credentials

Connector refers to the provider type (Microsoft, Google, etc.) in your Nylas application. Each connector can have multiple credentials, where each credential represents a combination of a provider’s client_id and client_secret.

When you create a connector, Nylas automatically creates a primary credential using the provider application credentials you provide. This primary credential is identified by the connector’s active_credential_id field. You can create additional credentials for the same connector to use different provider applications.

Each credential has a unique credential_id that you can use to specify which provider application should be used when authenticating users. Grants belong to specific credentials, and Nylas uses the credential’s provider application settings when making API calls on behalf of those grants.

Create a credential

To use a different provider application with an existing connector, you need to create a new credential for that connector.

First, create your new provider auth app (for example, a new Azure app or Google Cloud Platform project) or have your customer create it. Get the Application ID (client_id) and Secret Key (client_secret) from the provider.

Then, make a Create Credential request to create a new credential for your connector. Set credential_type to connector and include the provider’s client_id and client_secret in the credential_data object.

cURL

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "name": "CONNECTOR",
    "credential_type": "connector",
    "credential_data": {
      "client_id": "<CLIENT_ID>",         // PROVIDER_CLIENT_ID or NYLAS_CLIENT_ID, depending on credential type.
      "client_secret": "<CLIENT_SECRET>"  // PROVIDER_CLIENT_SECRET or NYLAS_CLIENT_SECRET, depending on credential type.
    }
  }'

The response includes a data.id field, which is the credential_id you’ll use when authenticating users with this provider application.

Authenticate users with a specific credential

After you create a credential, you can use its credential_id to authenticate users with that specific provider application. The method you use depends on your authentication flow.

Hosted OAuth authentication

If you’re using Hosted OAuth, add the credential_id as a query parameter when you build your authorization request. Include credential_id along with your other authorization parameters.

When the user completes authentication, they’re authenticated using the provider application associated with the specified credential_id. The token exchange process works the same as a standard Hosted OAuth flow—make a POST /v3/connect/token request to exchange the authorization code for a grant ID.

If you don’t specify a credential_id in your authorization request, Nylas uses the connector’s active credential (identified by the connector’s active_credential_id field).

The credential_id parameter works with response_type=code authorization requests. For Microsoft Service Account Admin Consent flows, the credential is specified when you create the credential, not in the authorization URL.

Bring Your Own Authentication

If you’re using Bring Your Own Authentication, include the credential_id in the settings object when you make a POST /v3/connect/custom request.

cURL

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connect/custom' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "provider": "google",
    "settings": {
      "refresh_token": "<REFRESH_TOKEN>"
    }
  }'

Add credential_id to the settings object in your request. The grant response includes the credential_id field, indicating which credential (and therefore which provider application) the grant is associated with.

If you don’t specify a credential_id in your request, Nylas uses the connector’s active credential.

Migrate grants between credentials

To migrate a user from one credential to another, you need to delete their existing grant and then re-authenticate them with the new credential.

First, make a Delete Grant request to delete the user’s current grant. Then, re-authenticate the user using one of the authentication methods above and specify the new credential_id. Nylas creates a new grant associated with the new credential.

When you delete a grant, Nylas creates a new grant ID when you re-authenticate the user. You’ll need to update your application code that references the old grant ID to use the new grant ID.