Update IAM principal - IAM Principals - API Reference

PATCH

https://api.us.nylas.com/v3/iam/principals/{principal_id}

Requires iam.principals.update on an active principal bound to the authenticated organization. Authenticate with an active, unexpired IAM credential of type api_key. Application API keys (including legacy API keys) and provider OAuth tokens cannot authorize IAM management endpoints. Use an existing IAM credential with these permissions, or create your first management credential in the Dashboard.

Each supplied field replaces its current value. Omitted fields stay unchanged. An empty roles or direct_permissions array clears that assignment set; an empty description clears the description. resource_binding replaces the single binding. Empty bodies, null values, unknown fields, and add/remove payloads are rejected. When active credentials exist, a non-Organization binding must resolve to exactly one application. A change that violates this invariant returns 409. The last active organization-bound IAM Admin cannot be deleted, disabled, or lose that binding or role.

IAM API KEY

Parameters

Path parameters

principal_id*string

ID of the principal in the authenticated organization.

Request body

namestring

Descriptive workload name. Surrounding whitespace is removed.

Example: "Support mailbox reader"

minLength: 1maxLength: 128

descriptionstring

Optional workload description.

maxLength: 1024

statusstring

Whether the principal or credential can authenticate.

activedisabled

rolesarray<string>

System or custom role IDs. Duplicate IDs are removed. Use the Dashboard to manage custom roles. Accepts up to 100 distinct IDs.

Example: ["role_system_messages_reader"]

direct_permissionsarray<string>

Canonical permission IDs assigned directly to the principal. Duplicate IDs are removed. Accepts up to 100 distinct IDs.

Example: ["messages.read"]

resource_bindingobject

Example: {"type":"grant","id":"<NYLAS_GRANT_ID>"}

Responses

request_idstring

Request ID for troubleshooting.

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}

curl --request PATCH \ --url "https://api.us.nylas.com/v3/iam/principals/${NYLAS_PRINCIPAL_ID}" \ --header "Authorization: Bearer $NYLAS_IAM_ADMIN_KEY" \ --header "Content-Type: application/json" \ --data '{"direct_permissions": ["messages.read"]}'