Create IAM principal - IAM Principals - API Reference

POST

https://api.us.nylas.com/v3/iam/principals

Requires iam.principals.create 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.

Creates a principal with exactly one resource binding. The organization comes from the caller credential; do not supply organization_id. Unknown fields and null values are rejected.

IAM API KEY

Request body

name*string

Descriptive workload name. Surrounding whitespace is removed.

Example: "Support mailbox reader"

minLength: 1maxLength: 128

descriptionstring

Optional workload description.

Default: ""

maxLength: 1024

statusstring

Whether the principal or credential can authenticate.

activedisabled

Default: "active"

rolesarray<string>

System or custom role IDs. Duplicate IDs are removed. Use the Dashboard to manage custom roles. Accepts up to 100 distinct IDs. 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. Accepts up to 100 distinct IDs.

Example: ["messages.read"]

resource_binding*object

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 POST \ --url "https://api.us.nylas.com/v3/iam/principals" \ --header "Authorization: Bearer $NYLAS_IAM_ADMIN_KEY" \ --header "Content-Type: application/json" \ --data '{"name": "Support mailbox reader", "roles": ["role_system_messages_reader"], "resource_binding": {"type": "grant", "id": "<NYLAS_GRANT_ID>"}}'