Skip to content
Skip to main content
PATCH
https://api.us.nylas.com/v3/iam/principals/{principal_id}

Update IAM principal

Updates a principal.

Each field you send replaces its current value, and fields you leave out stay the same. An empty roles or direct_permissions array removes all of them. An empty description removes the description. resource_binding replaces the principal's binding.

Nylas rejects empty bodies, null values, unknown fields, and add or remove payloads.

If the principal has active API keys, a binding other than Organization must resolve to exactly one application. A change that breaks this rule returns 409. You can't delete, disable, or remove the binding or role from the last active Organization-bound IAM Admin.

Requires an IAM API key with the iam.principals.update permission. Application API keys and access tokens don't work.

Parameters

Path parameters

principal_id*string

The principal's ID.

Request body

namestring

A name for the principal, such as the service that uses it. Nylas trims leading and trailing spaces.

Example: "Support mailbox reader"
minLength: 1maxLength: 128
descriptionstring

A description of what the principal is for.

maxLength: 1024
statusstring

Whether the principal's API keys can authenticate.

activedisabled
rolesarray<string>

Up to 100 system or custom role IDs. Nylas removes duplicates. Manage custom roles in the Dashboard.

Example: ["role_system_messages_reader"]
direct_permissionsarray<string>

Up to 100 permission IDs assigned directly to the principal. Nylas removes duplicates. See the permissions reference.

Example: ["messages.read"]
resource_bindingobject
Example: {"type":"grant","id":"<NYLAS_GRANT_ID>"}

Responses

request_idstring

The ID of the request.

dataobject
Example: {"id":"9Xf3LmQa2rP7sTuV0wYzB","organization_id":"<NYLAS_ORGANIZATION_ID>","name":"Support mailbox reader","description":"Reads the support mailbox","status":"active","roles":["role_system_messages_reader"],"direct_permissions":[],"resource_binding":{"type":"grant","id":"<NYLAS_GRANT_ID>"},"created_at":1791417600,"updated_at":1791417600}
PATCHhttps://api.us.nylas.com/v3/iam/principals/{principal_id}

Paste the authorization token required for this endpoint.

principal_idrequiredstring

The principal's ID.

Loading editor...

Autocomplete and validation come from this endpoint's request schema.