Create IAM credential - IAM Credentials - API Reference

POST

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

Requires iam.credentials.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 an api_key credential for an active principal. name and expires_at are required. expires_at is an integer Unix timestamp in seconds, measured from January 1, 1970 at 00:00:00 UTC. It must be after the current time and no more than 10 calendar years ahead. Store the secret securely: only this response includes it. Unknown fields and null values are rejected.

IAM API KEY

Parameters

Path parameters

principal_id*string

ID of the principal in the authenticated organization.

Request body

name*string

Descriptive workload name. Surrounding whitespace is removed.

Example: "Support worker key"

minLength: 1maxLength: 128

statusstring

Whether the principal or credential can authenticate.

activedisabled

Default: "active"

expires_at*integer<int64>

Required expiration as an integer number of seconds since the Unix epoch (January 1, 1970 at 00:00:00 UTC). For example, 1799193600 represents January 6, 2027 at 00:00:00 UTC. Use seconds, not milliseconds, an ISO 8601 string, or a duration. In JavaScript, use Math.floor(date.getTime() / 1000); in Python, use int(utc_datetime.timestamp()) with a timezone-aware UTC datetime. The value must be after the current time and no later than 10 calendar years from now. You can't change it after creation; create a replacement credential to use a different expiration.

Example: 1799193600

Responses

request_idstring

Request ID for troubleshooting.

dataobject

Example:

{"id":"8Lp2QwVm4rT6sYxN0cDzB","principal_id":"9Xf3LmQa2rP7sTuV0wYzB","type":"api_key","name":"Support worker key","status":"active","expires_at":1799193600,"created_at":1791417600,"updated_at":1791417600,"secret":"<NYLAS_IAM_API_KEY>"}

# Store the returned secret securely. Do not capture it in shared logs. EXPIRES_AT=$(python3 -c "import time; print(int(time.time()) + 90 * 86400)") curl --request POST \ --url "https://api.us.nylas.com/v3/iam/principals/${NYLAS_PRINCIPAL_ID}/credentials" \ --header "Authorization: Bearer $NYLAS_IAM_ADMIN_KEY" \ --header "Content-Type: application/json" \ --data "{\"name\": \"Support worker key\", \"expires_at\": ${EXPIRES_AT}}"