# Nylas IAM

Source: https://developer.nylas.com/docs/v3/auth/nylas-iam/

Nylas IAM controls which Nylas resources an API caller can access and what actions it can perform. Use it to issue least-privilege API keys for services, workers, and AI agents instead of sharing an application-wide key.

You configure Nylas IAM in the [Nylas Dashboard](https://dashboard.nylas.com/). This guide covers the Dashboard workflow. Nylas IAM management isn't available through the public API or Nylas CLI.

## How Nylas IAM works

Nylas has two separate authentication and authorization layers:

- **Provider authentication** connects a user's Google, Microsoft, IMAP, or other provider account to Nylas. The resulting [grant](/docs/v3/auth/) stores that connection and its provider OAuth scopes.
- **Nylas IAM authorization** controls which API callers can use Nylas resources. The resource boundary and permissions assigned to each caller define this access.

Provider scopes can't grant a caller permission that Nylas IAM denies. Likewise, Nylas IAM can't give a caller access that the connected provider account didn't authorize.

The IAM access model uses these objects:

| Object | Purpose |
| --- | --- |
| **Principal** | Represents an API caller and combines one resource binding with roles and direct permissions. |
| **Resource binding** | Limits the principal to one organization, application, workspace, or grant. |
| **Role** | Groups related permissions. Nylas provides system roles, and you can create custom roles. |
| **Permission** | Controls a specific Nylas action. You can inherit permissions from roles or assign them directly. |
| **Credential** | Provides an IAM API key that authenticates as its principal. |
| **Audit activity** | Records IAM configuration changes and allowed or denied requests made with IAM credentials. |

![Example Nylas IAM request flow. The Customer support app principal uses an IAM API key to read messages from support@example.com. Nylas checks the grant and action. If both match, it processes the request. Otherwise, it returns 403 Forbidden. Access Activity records the result.](/_images/auth/iam-access-model.svg)

In this example, the **Customer support app** principal can access only the `support@example.com` grant. The principal inherits permission to read messages from a role. A direct permission lets it update messages. At runtime, the IAM API key identifies the principal. Nylas checks that the request targets the assigned grant and uses an approved action. If either check fails, Nylas returns `403 Forbidden`. **Access Activity** records either result.

In the Dashboard, define a principal through **Name → Resource → Access**, then create one or more credentials that authenticate as that principal.

> **Info:** 
> **Start with the narrowest resource and permissions the caller needs.** For example, bind a mailbox-processing worker to one grant instead of the entire application.

## Create and configure a principal

A principal is an aggregation of permissions for an API caller. Create one principal for each distinct access pattern. You can issue more than one credential for a principal when callers need the same access.

1. In the Dashboard, open your organization's **Nylas IAM** page.
2. On the **Principals** tab, click **Create principal**.
3. In **Name**, enter a descriptive workload name. Add a description that identifies the service or agent that will use this principal, then continue to **Resource**.
4. Choose exactly one resource binding. For Application, Workspace, or Grant, select the application before selecting the final resource.
5. Continue to **Access** and select one or more roles, direct permissions, or both.
6. Review the configuration and click **Create principal**.

Every principal requires exactly one resource binding:

| Binding | Access boundary | Use it for |
| --- | --- | --- |
| **Grant** | One connected account, such as a mailbox or calendar. | A worker or agent that acts for one connected account. |
| **Workspace** | A group of grants inside one application. | A workload that serves one workspace or tenant. |
| **Application** | Every workspace and grant in one application. | A service that manages an entire Nylas application. |
| **Organization** | Everything in the organization, including billing and members. | Organization-wide administration where no narrower binding works. |

A Grant binding searches all grants in the selected application by grant ID or email address. It doesn't depend on workspace membership, so you can select grants in applications that have no workspaces, including unassigned grants.

You can edit a principal's name, description, status, resource binding, roles, and direct permissions. Disabling a principal prevents its credentials from accessing Nylas. Deleting a principal also deletes every IAM API key attached to it, and you can't undo the deletion.

## Configure roles and permissions

Roles make common access patterns reusable. On the **Roles** tab, choose a Nylas system role or create a custom role with the exact permissions your workload needs.

- **System roles** come from Nylas. You can assign them to principals but can't edit or delete them.
- **Custom roles** contain the permissions you select. You can create, edit, and delete them.
- **Direct permissions** apply to one principal without creating a role. Use them for exceptions or narrowly tailored access.

Permissions from roles and direct assignments are additive, but the resource binding remains the outer access boundary. When a role has permissions that the selected binding doesn't support, the Dashboard separates them into **Effective permissions** and **Ignored permissions**. Ignored permissions don't grant access at that binding level.

> **Info:** 
> **Prefer roles for access patterns shared by multiple principals.** Use direct permissions when only one principal needs the exception.

## Create and manage IAM API keys

An IAM API key is a credential attached to a principal. Requests made with the key inherit the principal's resource binding, roles, direct permissions, and status.

1. On the **Credentials** tab, click **Create key**.
2. Enter a descriptive name and select an active principal.
3. Set an expiration in days, or leave the field empty for no expiration.
4. Click **Create** and copy the secret immediately. The Dashboard displays it only once.
5. Store the secret in a managed secrets service and inject it into your backend at runtime.

Use an IAM API key anywhere you use a Nylas API key. Send it as a Bearer token or pass it to a Nylas SDK:

```bash
curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages" \
  --header "Authorization: Bearer <NYLAS_IAM_API_KEY>"
```

IAM API keys differ from application API keys:

| Key type | Access model | Management location |
| --- | --- | --- |
| **IAM API key** | Inherits one principal's resource binding and permissions. | Organization **Nylas IAM** page |
| **Application API key** | Provides application-wide access to the application's connected accounts. | Application **API keys** page |

Prefer IAM API keys for production workloads that don't need application-wide access. Keep both key types out of source code, client applications, logs, prompts, and error messages.

To rotate an IAM API key without downtime, create a replacement credential for the same principal, deploy the new secret, verify that requests succeed, and then delete the old credential. You can edit a key to change its name or set its status to **Disabled**. A disabled or deleted key no longer authenticates and returns `401 Unauthorized`.

## Review and troubleshoot IAM activity

Nylas IAM retains both audit views for 400 days:

- **Config Changes** records changes to principals, credentials, roles, permissions, and resource bindings. Filter by event, resource type, time, principal ID, credential ID, resource ID, actor, or Request ID.
- **Access Activity** records allowed and denied API, authentication, and MCP requests made with IAM credentials. Filter by result, principal, API key, time, application, grant, workspace, or Request ID.

When an Access Activity event has a Request ID and application, use its request link to open the corresponding API, authentication, or MCP logs. This connects the authorization decision to the underlying request without exposing credential secrets.

### Troubleshoot `401 Unauthorized`

A `401` response means Nylas couldn't authenticate the credential. In the **Credentials** tab, confirm that the IAM API key still exists and has an **Active** status. Also confirm that its principal is active and that the caller is sending the current secret as a Bearer token.

Because the Dashboard displays a key secret only once, create a replacement if the stored value is unavailable. Never place a key in a ticket, chat message, log, or screenshot while troubleshooting.

### Troubleshoot `403 Forbidden`

A `403` response means Nylas authenticated the IAM API key but didn't authorize the request. Open **Access Activity**, filter by Request ID or API key, and inspect the denial reason. Then confirm that:

- The principal's resource binding includes the application, workspace, or grant in the request.
- The principal has an effective permission for the requested action.
- A role permission isn't listed as ignored for the selected resource binding.

Provider OAuth scopes are a separate authorization layer. If IAM allowed the request but the provider rejected the operation, inspect the grant's provider scopes and the provider-specific error instead.

## What's next

- [Authentication overview](/docs/v3/auth/) for provider authentication methods and grants
- [Security best practices](/docs/dev-guide/best-practices/) for protecting credentials and user data
- [Nylas MCP server](/docs/dev-guide/mcp/) for connecting agents with an IAM API key
- [Troubleshoot Nylas API errors](/docs/v3/troubleshooting/) for common API and provider failures