Skip to content
Skip to main content
POST
https://api.us.nylas.com/v3/iam/principals

Create IAM principal

Creates a principal with one resource binding.

Nylas sets the organization from your API key, so don't send organization_id. Nylas rejects unknown fields and null values.

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

Request body

name*string

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.

Default: ""
maxLength: 1024
statusstring

Whether the principal's API keys can authenticate.

activedisabled
Default: "active"
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_binding*object
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}
POSThttps://api.us.nylas.com/v3/iam/principals

Paste the authorization token required for this endpoint.

Loading editor...

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