NYnylas
IAM principals

Create IAM principal

Changed on

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.

post/v3/iam/principals

Request

Request body

namestring required

Descriptive workload name. Surrounding whitespace is removed.

descriptionstring

Optional workload description.

status'active' | 'disabled'

Whether the principal or credential can authenticate.

rolesstring[]

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.

direct_permissionsstring[]

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 request

{
  "name": "Support mailbox reader",
  "roles": [
    "role_system_messages_reader"
  ],
  "direct_permissions": [
    "messages.read"
  ],
  "resource_binding": {
    "type": "grant",
    "id": "<NYLAS_GRANT_ID>"
  }
}

Response

OK

request_idstring

Request ID for troubleshooting.

Example response

{
  "data": {
    "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
  }
}

Changes