# IAM principals

Source: https://developer.nylas.com/docs/reference/api/iam-principals/

Manage reusable IAM identities, their resource bindings, roles, and direct permissions. Requests require an organization-bound IAM API key with the corresponding `iam.principals.*` permission. Start with the [IAM API guide](/docs/v3/auth/nylas-iam/manage-principals-with-api/).

## Principal and credential limits

IAM limits start with a base allowance and increase as you bind principals to resources. **N** is the number of distinct applications, workspaces, and grants directly referenced by at least one non-deleted principal's resource binding. Resources without a principal binding don't count. Multiple principals bound to the same resource count that resource once. Organization bindings don't increase N.

| Object                              | Limit                                                |
| ----------------------------------- | ---------------------------------------------------- |
| Principals per organization         | `100 + 2N`                                           |
| Active credentials per organization | `2 × (100 + 2N)`                                     |
| Credentials per principal           | 10 total, including disabled and expired credentials |

Suppose your organization has **1 application, 2 workspaces, and 3 grants**. The limits depend on which resources have principal bindings:

| Principal bindings                                                        | N   | Principal limit | Active credential limit |
| ------------------------------------------------------------------------- | --- | --------------- | ----------------------- |
| No principals are bound to any of the six resources                       | 0   | 100             | 200                     |
| One principal is bound to one grant                                       | 1   | 102             | 204                     |
| Ten principals are all bound to the same grant                            | 1   | 102             | 204                     |
| At least one principal is bound to each application, workspace, and grant | 6   | 112             | 224                     |
| Principals are bound only to the organization                             | 0   | 100             | 200                     |

Binding a principal to a grant counts that grant; it doesn't also count the grant's parent application or workspace. Those resources count only when they have their own principal bindings. With 10 distinct bound resources, the limits are 120 principals and 240 active credentials. Every principal still has a separate limit of 10 total credentials.

Deleting a credential frees its per-principal slot; disabling it doesn't. Disabling or deleting a key releases its active organization capacity. Expired keys release organization capacity when background reconciliation processes them. Nylas rejects a binding change that lowers the organization's principal limit below current usage.

A quota failure returns **400** with `error.code` set to `api.resource_limit_exceeded`, `error.type` set to `api.invalid_request`, and `error.details` containing `resource_type`, `limit`, and `current`. Remove unused objects or disable active keys as appropriate before retrying. Reserve credential capacity for rotation.


## Endpoints

- **GET** `/v3/iam/principals` - [List IAM principals](https://developer.nylas.com/docs/reference/api/iam-principals/list-iam-principals/)
- **POST** `/v3/iam/principals` - [Create IAM principal](https://developer.nylas.com/docs/reference/api/iam-principals/create-iam-principal/)
- **GET** `/v3/iam/principals/{principal_id}` - [Get IAM principal](https://developer.nylas.com/docs/reference/api/iam-principals/get-iam-principal/)
- **PATCH** `/v3/iam/principals/{principal_id}` - [Update IAM principal](https://developer.nylas.com/docs/reference/api/iam-principals/update-iam-principal/)
- **DELETE** `/v3/iam/principals/{principal_id}` - [Delete IAM principal](https://developer.nylas.com/docs/reference/api/iam-principals/delete-iam-principal/)