---
title: "Create IAM credential"
method: POST
path: "/v3/iam/principals/{principal_id}/credentials"
tags: ["IAM credentials"]
---

# Create IAM credential

`POST /v3/iam/principals/{principal_id}/credentials`

## Request

- Base URL: `https://api.us.nylas.com`
- URL: `https://api.us.nylas.com/v3/iam/principals/{principal_id}/credentials`
- Auth: HTTP bearer

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](/docs/v3/auth/nylas-iam/manage-principals-with-api/#create-a-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.

## Request body

- CredentialCreate
  - `name` string, required: Descriptive workload name. Surrounding whitespace is removed.
  - `status` 'active' | 'disabled': Whether the principal or credential can authenticate.
  - `expires_at` integer, required: 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.

## Response `200`

OK

- object
  - `request_id` string: Request ID for troubleshooting.
  - `data` CreatedCredential
    - `id` string, required: Opaque credential ID.
    - `principal_id` string, required: ID of the principal that owns this credential.
    - `type` 'api_key', required: Supported IAM credential type.
    - `name` string, required: Descriptive workload name. Surrounding whitespace is removed.
    - `status` 'active' | 'disabled', required: Whether the principal or credential can authenticate.
    - `expires_at` integer, nullable, 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. Newly created credentials always have an expiration.
    - `created_at` integer, required: Unix timestamp in seconds.
    - `updated_at` integer, required: Unix timestamp in seconds.
    - `secret` string, required: IAM API key secret. Returned only once, on creation. Store securely; never log this response.

## Other responses

- `400`: Invalid request or object quota exceeded
- `401`: Invalid, disabled, deleted, or expired authentication credential
- `403`: Missing management permission or organization binding
- `404`: Principal or credential not found in this organization
- `409`: Conflicting principal or credential state
- `429`: Too many requests

## Changes

- **2026-10-10** `fb580f0d35d2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nylas/apis/nylas-api/changes/v3/iam/principals/:principal_id/credentials/post.md)

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) - [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nylas/apis/nylas-api/revisions/7782a3e3ab70?raw)