Nylas IAM credentials API

openapi: 3.2.0
info:
  title: Nylas IAM credentials API
  version: v3
  summary: The complete Nylas v3 API — Email, Calendar, Contacts, Notetaker, Scheduling, Administration, and Migration.
  description: The Nylas API is designed using the REST ideology to provide simple and predictable URIs to access and modify objects. Requests support standard HTTP methods like `GET`, `PUT`, `POST`, and `DELETE`, and standard status codes. Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise. You can use the Nylas Postman collection to quickly start using the Nylas APIs. For more information, check out the Nylas Postman collection documentation.
  contact:
    url: https://www.nylas.com/
servers:
- url: https://api.us.nylas.com
  description: U.S.
- url: https://api.eu.nylas.com
  description: E.U.
security:
- ACCESS_TOKEN: []
- NYLAS_API_KEY: []
tags:
- name: IAM credentials
  description: Create and manage IAM credentials of type `api_key` attached to principals. Credentials inherit the principal's policy, and creation returns the secret only once. Requests require an organization-bound IAM API key with the corresponding `iam.credentials.*` permission. See credential creation and rotation.
paths:
  /v3/iam/principals/{principal_id}/credentials:
    parameters:
    - in: path
      name: principal_id
      required: true
      schema:
        type: string
      description: ID of the principal in the authenticated organization.
    get:
      summary: List IAM credentials
      tags:
      - IAM credentials
      operationId: list-iam-credentials
      description: 'Requires `iam.credentials.read` 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.


        Never returns the credential secret.


        Use next_cursor from the response as page_token on the next request. When next_cursor is absent, there are no more results.'
      security:
      - IAM_API_KEY: []
      x-permissions:
      - iam.credentials.read
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: Maximum results per page.
      - in: query
        name: page_token
        schema:
          type: string
          maxLength: 2048
        description: Opaque next_cursor from the previous response.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    description: Request ID for troubleshooting.
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Credential'
                  next_cursor:
                    type: string
                    description: Opaque cursor. Absent on the final page. Pass as page_token.
              example:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                data:
                - id: 8Lp2QwVm4rT6sYxN0cDzB
                  principal_id: 9Xf3LmQa2rP7sTuV0wYzB
                  type: api_key
                  name: Support worker key
                  status: active
                  expires_at: 1799193600
                  created_at: 1791417600
                  updated_at: 1791417600
        '400':
          description: Invalid request or object quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid, disabled, deleted, or expired authentication credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing management permission or organization binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Principal or credential not found in this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflicting principal or credential state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request GET \\\n  --url \"https://api.us.nylas.com/v3/iam/principals/${NYLAS_PRINCIPAL_ID}/credentials\" \\\n  --header \"Authorization: Bearer $NYLAS_IAM_ADMIN_KEY\"\n"
    post:
      summary: Create IAM credential
      tags:
      - IAM credentials
      operationId: create-iam-credential
      description: '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.'
      security:
      - IAM_API_KEY: []
      x-permissions:
      - iam.credentials.create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    description: Request ID for troubleshooting.
                  data:
                    $ref: '#/components/schemas/CreatedCredential'
              example:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                data:
                  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>
        '400':
          description: Invalid request or object quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid, disabled, deleted, or expired authentication credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing management permission or organization binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Principal or credential not found in this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflicting principal or credential state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "# Store the returned secret securely. Do not capture it in shared logs.\nEXPIRES_AT=$(python3 -c \"import time; print(int(time.time()) + 90 * 86400)\")\n\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/iam/principals/${NYLAS_PRINCIPAL_ID}/credentials\" \\\n  --header \"Authorization: Bearer $NYLAS_IAM_ADMIN_KEY\" \\\n  --header \"Content-Type: application/json\" \\\n  --data \"{\\\"name\\\": \\\"Support worker key\\\", \\\"expires_at\\\": ${EXPIRES_AT}}\"\n"
      - lang: javascript
        label: Node.js (HTTP)
        source: "const requiredEnvironment = (name) => {\n  const value = process.env[name]?.trim();\n  if (!value) throw new Error(`Set ${name} before running this example`);\n  return value;\n};\nconst adminKey = requiredEnvironment(\"NYLAS_IAM_ADMIN_KEY\");\n// Store data.secret in your secrets service. Never log the response.\nconst principalId = encodeURIComponent(\n  requiredEnvironment(\"NYLAS_PRINCIPAL_ID\"),\n);\nconst response = await fetch(\n  `https://api.us.nylas.com/v3/iam/principals/${principalId}/credentials`,\n  {\n    method: \"POST\",\n    signal: AbortSignal.timeout(30000),\n    headers: {\n      Authorization: `Bearer ${adminKey}`,\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({\n      name: \"Support worker key\",\n      expires_at: Math.floor(Date.now() / 1000) + 90 * 86400,\n    }),\n  },\n);\nif (!response.ok)\n  throw new Error(`Credential creation failed (${response.status})`);\nconst { data: credential } = await response.json();\n// Pass credential.secret directly to your secrets-service client here.\n// Save credential.id so you can rotate or revoke this key later.\n"
      - lang: python
        label: Python (HTTP)
        source: "import json\nimport os\nimport time\nfrom urllib.parse import quote\nfrom urllib.request import Request, urlopen\n\nprincipal_id = quote(os.environ[\"NYLAS_PRINCIPAL_ID\"], safe=\"\")\nrequest = Request(\n    f\"https://api.us.nylas.com/v3/iam/principals/{principal_id}/credentials\",\n    method=\"POST\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['NYLAS_IAM_ADMIN_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    data=json.dumps({\n        \"name\": \"Support worker key\",\n        \"expires_at\": int(time.time()) + 90 * 86400,\n    }).encode(),\n)\nwith urlopen(request, timeout=30) as response:\n    credential = json.load(response)[\"data\"]\n# Pass credential[\"secret\"] directly to your secrets-service client here.\n# Save credential[\"id\"] for rotation or revocation. Never log the response.\n"
  /v3/iam/principals/{principal_id}/credentials/{credential_id}:
    parameters:
    - in: path
      name: principal_id
      required: true
      schema:
        type: string
      description: ID of the principal in the authenticated organization.
    - in: path
      name: credential_id
      required: true
      schema:
        type: string
      description: ID of the credential in the authenticated organization.
    get:
      summary: Get IAM credential
      tags:
      - IAM credentials
      operationId: get-iam-credential
      description: 'Requires `iam.credentials.read` 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.


        Never returns the credential secret.'
      security:
      - IAM_API_KEY: []
      x-permissions:
      - iam.credentials.read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    description: Request ID for troubleshooting.
                  data:
                    $ref: '#/components/schemas/Credential'
              example:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                data:
                  id: 8Lp2QwVm4rT6sYxN0cDzB
                  principal_id: 9Xf3LmQa2rP7sTuV0wYzB
                  type: api_key
                  name: Support worker key
                  status: active
                  expires_at: 1799193600
                  created_at: 1791417600
                  updated_at: 1791417600
        '400':
          description: Invalid request or object quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid, disabled, deleted, or expired authentication credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing management permission or organization binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Principal or credential not found in this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflicting principal or credential state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request GET \\\n  --url \"https://api.us.nylas.com/v3/iam/principals/${NYLAS_PRINCIPAL_ID}/credentials/${NYLAS_CREDENTIAL_ID}\" \\\n  --header \"Authorization: Bearer $NYLAS_IAM_ADMIN_KEY\"\n"
    patch:
      summary: Update IAM credential
      tags:
      - IAM credentials
      operationId: update-iam-credential
      description: 'Requires `iam.credentials.update` 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.


        Updates only name and/or status. Expiration, type, principal, and secret cannot be changed. Omitted fields stay unchanged. A disabled principal cannot reactivate a credential. Empty bodies, null values, and unknown fields are rejected.'
      security:
      - IAM_API_KEY: []
      x-permissions:
      - iam.credentials.update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    description: Request ID for troubleshooting.
                  data:
                    $ref: '#/components/schemas/Credential'
              example:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                data:
                  id: 8Lp2QwVm4rT6sYxN0cDzB
                  principal_id: 9Xf3LmQa2rP7sTuV0wYzB
                  type: api_key
                  name: Support worker key
                  status: active
                  expires_at: 1799193600
                  created_at: 1791417600
                  updated_at: 1791417600
        '400':
          description: Invalid request or object quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid, disabled, deleted, or expired authentication credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing management permission or organization binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Principal or credential not found in this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflicting principal or credential state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request PATCH \\\n  --url \"https://api.us.nylas.com/v3/iam/principals/${NYLAS_PRINCIPAL_ID}/credentials/${NYLAS_CREDENTIAL_ID}\" \\\n  --header \"Authorization: Bearer $NYLAS_IAM_ADMIN_KEY\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\"status\": \"disabled\"}'\n"
    delete:
      summary: Delete IAM credential
      tags:
      - IAM credentials
      operationId: delete-iam-credential
      description: 'Requires `iam.credentials.delete` 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.


        Permanently deletes the credential. It can no longer authenticate. A successful response contains request_id and no data.'
      security:
      - IAM_API_KEY: []
      x-permissions:
      - iam.credentials.delete
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    description: Request ID for troubleshooting.
              example:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
        '400':
          description: Invalid request or object quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid, disabled, deleted, or expired authentication credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing management permission or organization binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Principal or credential not found in this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflicting principal or credential state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request DELETE \\\n  --url \"https://api.us.nylas.com/v3/iam/principals/${NYLAS_PRINCIPAL_ID}/credentials/${NYLAS_CREDENTIAL_ID}\" \\\n  --header \"Authorization: Bearer $NYLAS_IAM_ADMIN_KEY\"\n"
components:
  schemas:
    CredentialCreate:
      type: object
      additionalProperties: false
      required:
      - name
      - expires_at
      properties:
        name:
          type: string
          description: Descriptive workload name. Surrounding whitespace is removed.
          minLength: 1
          maxLength: 128
          example: Support worker key
        status:
          type: string
          description: Whether the principal or credential can authenticate.
          enum:
          - active
          - disabled
          default: active
        expires_at:
          type: integer
          format: int64
          description: 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
    Credential:
      type: object
      required:
      - id
      - principal_id
      - type
      - name
      - status
      - expires_at
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Opaque credential ID.
        principal_id:
          type: string
          description: ID of the principal that owns this credential.
        type:
          type: string
          description: Supported IAM credential type.
          enum:
          - api_key
        name:
          type: string
          description: Descriptive workload name. Surrounding whitespace is removed.
          minLength: 1
          maxLength: 128
          example: Support worker key
        status:
          type: string
          description: Whether the principal or credential can authenticate.
          enum:
          - active
          - disabled
        expires_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 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:
          type: integer
          format: int64
          description: Unix timestamp in seconds.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp in seconds.
      example:
        id: 8Lp2QwVm4rT6sYxN0cDzB
        principal_id: 9Xf3LmQa2rP7sTuV0wYzB
        type: api_key
        name: Support worker key
        status: active
        expires_at: 1799193600
        created_at: 1791417600
        updated_at: 1791417600
    CredentialUpdate:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name:
          type: string
          description: Descriptive workload name. Surrounding whitespace is removed.
          minLength: 1
          maxLength: 128
          example: Support worker key
        status:
          type: string
          description: Whether the principal or credential can authenticate.
          enum:
          - active
          - disabled
    Error:
      type: object
      properties:
        request_id:
          type: string
          description: Request ID for troubleshooting.
        error:
          type: object
          required:
          - type
          - message
          properties:
            code:
              type: string
              description: Error code.
            type:
              type: string
              description: Error category.
            message:
              type: string
              description: Description of the failure.
            details:
              type: object
              description: Additional error context. Quota errors include resource_type, limit, and current.
              properties:
                resource_type:
                  type: string
                limit:
                  type: integer
                current:
                  type: integer
    CreatedCredential:
      type: object
      required:
      - id
      - principal_id
      - type
      - name
      - status
      - expires_at
      - created_at
      - updated_at
      - secret
      properties:
        id:
          type: string
          description: Opaque credential ID.
        principal_id:
          type: string
          description: ID of the principal that owns this credential.
        type:
          type: string
          description: Supported IAM credential type.
          enum:
          - api_key
        name:
          type: string
          description: Descriptive workload name. Surrounding whitespace is removed.
          minLength: 1
          maxLength: 128
          example: Support worker key
        status:
          type: string
          description: Whether the principal or credential can authenticate.
          enum:
          - active
          - disabled
        expires_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 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:
          type: integer
          format: int64
          description: Unix timestamp in seconds.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp in seconds.
        secret:
          type: string
          description: IAM API key secret. Returned only once, on creation. Store securely; never log this response.
          example: <NYLAS_IAM_API_KEY>
      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>
  securitySchemes:
    IAM_API_KEY:
      type: http
      scheme: bearer
      bearerFormat: IAM API key
      description: An active, unexpired IAM credential of type `api_key` whose principal is active, has an Organization resource binding, and has the required IAM management permission. 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). Application API keys (including legacy API keys) and provider OAuth tokens cannot authorize IAM management endpoints.
    ACCESS_TOKEN:
      scheme: bearer
      type: http
      bearerFormat: NYLAS_ACCESS_TOKEN
      description: 'The Nylas **access token** for a specific grant. Issued as part of OAuth 2.1 flow token

        exchange.'
    NYLAS_API_KEY:
      scheme: bearer
      type: http
      bearerFormat: NYLAS_API_KEY
      description: 'The Nylas **API key** provides application-level access to APIs and all grants. You can

        generate these from the Dashboard. Learn more about [authorizing requests](/docs/v3/auth/).'
    SCHEDULER_SESSION_TOKEN:
      scheme: bearer
      type: http
      bearerFormat: Session ID
      description: The Nylas Scheduler **session ID** that Scheduler UI Components use to authorize API requests.
x-provenance:
  method: harvested
  publisher: Nylas
  source: https://developer.nylas.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)