# NylasConnect class overview

Source: https://developer.nylas.com/docs/v3/auth/nylas-connect/nylasconnect-class/

The `NylasConnect` class is the core of the Nylas Connect library. It provides methods for OAuth authentication, token management, and grant creation and management. **The primary use case for NylasConnect is integrating with external identity providers** (IDPs) like Auth0, Clerk, Google Identity, and WorkOS, allowing you to link your users' existing identities with their email accounts.

> **Using with External Identity Providers:** 
> Most applications should integrate NylasConnect with an external identity provider. This allows you to:
> 
> - Use your existing authentication system
> - Link user identities across your application and email services
> - Make API calls using your IDP tokens instead of managing separate API keys
> 
> See the [External Identity Provider integration guide](/docs/v3/auth/nylas-connect/use-external-idp/) to get started.

## Basic configuration

When using NylasConnect with an external identity provider, configure it with the `identityProviderToken` callback:

```ts


const nylasConnect = new NylasConnect({
  clientId: process.env.NYLAS_CLIENT_ID!,
  redirectUri: process.env.NYLAS_REDIRECT_URI!,
  apiUrl: process.env.NYLAS_API_URL || "https://api.us.nylas.com",
  // Provide your IDP token for authenticated API calls
  identityProviderToken: async () => {
    return await getYourIdpToken();
  },
  environment: "production",
  persistTokens: true,
  debug: false,
  logLevel: "error",
});

// Set up authentication state monitoring
nylasConnect.onConnectStateChange((event, session, data) => {
  console.log("Auth state changed:", event);

  switch (event) {
    case "SIGNED_IN":
      // Handle successful connection
      console.log("Connected:", session?.grantInfo?.email);
      break;
    case "SIGNED_OUT":
      // Handle disconnection
      console.log("Disconnected");
      break;
    case "CONNECT_ERROR":
      // Handle authentication errors
      console.error("Auth error:", data?.error);
      break;
  }
});
```

## `ConnectConfig`

The `NylasConnect` constructor accepts a `ConnectConfig` object with the following options.


## Integration patterns

### External identity provider integration (Recommended)

The recommended way to use NylasConnect is with an external identity provider. This pattern allows you to:

- **Unified authentication**: Users authenticate once with your IDP (Auth0, Clerk, Google, WorkOS, etc.)
- **Seamless email access**: Link their email accounts to their existing identity
- **Simplified API calls**: Use IDP tokens instead of managing separate API keys
- **Enhanced security**: Leverage your IDP's security features and compliance

**Get started:** Follow the [External Identity Provider guide](/docs/v3/auth/nylas-connect/use-external-idp/) for implementation steps with your chosen provider.

### Standalone OAuth integration

You can also use NylasConnect for direct OAuth flows without an external IDP. This is suitable for:

- Simple applications that only need email access
- Prototypes and proof-of-concepts
- Scenarios where you don't have an existing authentication system

For standalone usage, see the [Nylas Connect overview](/docs/v3/auth/nylas-connect/) for basic implementation.

## Methods

The `NylasConnect` class includes the following methods. Click on any method name to view its detailed documentation.

### Authentication methods


### Callback methods


### Grant management methods


### Utility methods


## Property types

### `ConnectError`

`ConnectError` extends the standard `Error` interface and adds fields for better error handling.

| Property        | Type    | Description                                                    |
| --------------- | ------- | -------------------------------------------------------------- |
| `code`          | string  | An error code for programmatic error handling.                 |
| `description`   | string? | A human-readable description of the error.                     |
| `docsUrl`       | string? | A link to relevant documentation.                              |
| `fix`           | string? | A suggested solution for resolving the error.                  |
| `originalError` | Error?  | The original error, if the `ConnectError` wraps another error. |

### `Environment`

|                 |                                        |
| --------------- | -------------------------------------- |
| **Name**        | `Environment`                          |
| **Description** | Your project's deployment environment. |
| **Enum**        | `development \| staging \| production` |

### `ProviderScopes`

Default scope settings for different providers.

```ts
type ProviderScopes = {
  google?: GoogleScope[];
  microsoft?: MicrosoftScope[];
  yahoo?: YahooScope[];
  imap?: never; // IMAP doesn't support scopes
  icloud?: string[]; // iCloud uses custom scopes
};
```

```ts {4-7} [providerScopes-Example]
const nylasConnect = new NylasConnect({
  clientId: "<NYLAS_CLIENT_ID>",
  redirectUri: "https://yourapp.com/callback",
  defaultScopes: {
    google: ["https://www.googleapis.com/auth/gmail.readonly"],
    microsoft: ["https://graph.microsoft.com/Mail.Read"],
  },
});
```