- API reference
- IAM principals
- Get IAM principal
GET
https://api.us.nylas.com/v3/iam/principals/{principal_id}Get IAM principal
Returns a principal's details.
Requires an IAM API key with the iam.principals.read permission. Application API keys and access tokens don't work.
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}name*stringA name for the principal, such as the service that uses it. Nylas trims leading and trailing spaces.
Example:
"Support mailbox reader"minLength: 1maxLength: 128
roles*array<string>Up to 100 system or custom role IDs. Nylas removes duplicates. Manage custom roles in the Dashboard.
Example:
["role_system_messages_reader"]direct_permissions*array<string>Up to 100 permission IDs assigned directly to the principal. Nylas removes duplicates. See the permissions reference.
Example:
["messages.read"]The request is invalid, or the organization has reached its quota.
The API key's principal is missing the required permission or an Organization binding.
The change conflicts with the principal's or API key's current state.