Nylas Manage API keys API

openapi: 3.2.0
info:
  title: Nylas Manage API keys 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: Manage API keys
  description: 'The Manage API Keys endpoints let you create, list, and delete API keys from your Nylas application outside of the Nylas Dashboard.


    ## Nylas Service Account


    ⚠️ Before you can use the Manage API Keys endpoints, you need to create a Nylas Service Account. If you have a contract with us, you can contact Nylas Support for more information.


    After Nylas Support creates a Service Account for your application, they send you a JSON file with the following information:


    ```json

    {

    "type": "service_account",

    "private_key_id": "",

    "private_key": "",

    "organization_id": "",

    "region": "us"

    "permissions": ["apikey.create", "apikey.delete", "apikey.get"]

    }

    ```


    You use the information in this file to generate the headers that sign your requests (for example, the `X-Nylas-Signature` header uses your private key''s RSA, a 2048-bit key, and an SHA-256 hashed string of the path, method, timestamp, nonce, and payload.). Be sure to store this information securely.'
paths:
  /v3/admin/applications/{application_id}/api-keys:
    parameters:
    - in: path
      schema:
        type: string
      name: application_id
      required: true
      description: ID of the Nylas application to access.
    - in: header
      name: X-Nylas-Signature
      schema:
        type: string
      required: true
      description: 'A Base64-encoded signature using your private key''s RSA with a 2048-bit key and an SHA-256 hashed

        string of the path, method, timestamp, nonce, and payload.'
    - in: header
      name: X-Nylas-Kid
      schema:
        type: string
      required: true
      description: The `private_key_id` from your Service Account JSON file.
    - in: header
      name: X-Nylas-Nonce
      schema:
        type: string
      required: true
      description: 'A randomly generated nonce. Each request needs to have a unique nonce. If you try to reuse a

        nonce, Nylas rejects the request.'
    - in: header
      name: X-Nylas-Timestamp
      schema:
        type: number
      required: true
      description: 'The time when you submit your request, in seconds using the Unix timestamp format. This timestamp should fall within

        a 5-minute window of your real request time.'
    post:
      summary: Create API key
      tags:
      - Manage API keys
      operationId: create-api-key
      x-beta: true
      description: '⚠️ Before you can use the Manage API Keys endpoints, you need to create a Nylas Service Account.


        Creates an API key for the specified Nylas application.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A short, descriptive name for the API key.
                  example: example-key
                expires_in:
                  type: integer
                  description: How long the API key will be valid, in days. Accepts 1 to 9125. If you leave it out, the key is valid for 9125 days (25 years).
                  minimum: 1
                  maximum: 9125
                  example: 90
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl -X POST \"https://api.us.nylas.com/v3/admin/applications/<NYLAS_APPLICATION_ID>/api-keys\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n  -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n  -H \"X-Nylas-Nonce: <NONCE>\" \\\n  -H \"X-Nylas-Timestamp: 1676412353123\" \\\n  -d '{\n    \"name\": \"example-key\",\n    \"expires_in\": 3600\n  }'"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    description: ID of the request.
                    example: 5fa64c92-e840-4357-86b9-2aa364d35b88
                  data:
                    type: object
                    properties:
                      api_key:
                        type: string
                        description: The API key.
                        example: <NYLAS_API_KEY>
                      application_id:
                        type: string
                        description: The application ID associated with the API key.
                        example: ad410018-d306-43f9-8361-fa5d7b2172e0
                      created_at:
                        type: number
                        description: When the API key was created, in seconds using the Unix timestamp format.
                        example: 1742932766
                      expires_at:
                        type: number
                        description: When the API key will expire, in seconds using the Unix timestamp format.
                        example: 1753300766
                      id:
                        type: string
                        description: The API key ID.
                        example: <NYLAS_API_KEY_ID>
                      name:
                        type: string
                        description: The name of the API key.
                        example: example-key
                      permissions:
                        type: array
                        description: The permissions assigned to the API key. Nylas always sets this to `["all"]`.
                        items:
                          type: string
                        example:
                        - all
                      status:
                        type: string
                        description: The status of the API key.
                        example: active
                      updated_at:
                        type: number
                        description: 'When the API key was last updated, in seconds using the Unix timestamp format. For new API keys,

                          this value is the same as `created_at`.'
                        example: 1742932766
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
    get:
      summary: Get all API keys
      tags:
      - Manage API keys
      operationId: get-api-keys
      x-beta: true
      description: '⚠️ Before you can use the Manage API Keys endpoints, you need to create a Nylas Service Account.


        Returns a list of API keys associated with the specified Nylas application. The response includes up to 100 keys and isn''t paginated. It never includes the secret key value, which Nylas only returns when you create a key.'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://api.us.nylas.com/v3/admin/applications/<NYLAS_APPLICATION_ID>/api-keys\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n  -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n  -H \"X-Nylas-Nonce: <NONCE>\" \\\n  -H \"X-Nylas-Timestamp: 1676412353123\""
      responses:
        '200':
          $ref: '#/components/responses/get-api-keys-200'
        '204':
          description: The application has no API keys. Nylas returns no response body.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
  /v3/admin/applications/{application_id}/api-keys/{api_key_id}:
    parameters:
    - schema:
        type: string
      name: application_id
      in: path
      required: true
      description: ID of the Nylas application to access.
    - schema:
        type: string
      name: api_key_id
      in: path
      required: true
      description: ID of the API key to access.
    - in: header
      name: X-Nylas-Signature
      schema:
        type: string
      required: true
      description: 'A Base64-encoded signature using your private key''s RSA with a 2048-bit key and an SHA-256 hashed

        string of the path, method, timestamp, nonce, and payload.'
    - in: header
      name: X-Nylas-Kid
      schema:
        type: string
      required: true
      description: The `private_key_id` from your Service Account JSON file.
    - in: header
      name: X-Nylas-Nonce
      schema:
        type: string
      required: true
      description: 'A randomly generated nonce. Each request needs to have a unique nonce. If you try to reuse a

        nonce, Nylas rejects the request.'
    - in: header
      name: X-Nylas-Timestamp
      schema:
        type: number
      required: true
      description: 'The time when you submit your request, in seconds using the Unix timestamp format. This timestamp should fall within

        a 5-minute window of your real request time.'
    get:
      summary: Get API key
      tags:
      - Manage API keys
      operationId: get-api-key
      x-beta: true
      description: '⚠️ Before you can use the Manage API Keys endpoints, you need to create a Nylas Service Account.


        Returns the specified API key.'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://api.us.nylas.com/v3/admin/applications/<NYLAS_APPLICATION_ID>/api-keys/<API_KEY_ID>\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n  -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n  -H \"X-Nylas-Nonce: <NONCE>\" \\\n  -H \"X-Nylas-Timestamp: 1676412353123\""
      responses:
        '200':
          $ref: '#/components/responses/get-api-key-200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
    delete:
      summary: Delete API key
      tags:
      - Manage API keys
      operationId: delete-api-key
      x-beta: true
      description: '⚠️ Before you can use the Manage API Keys endpoints, you need to create a Nylas Service Account.


        Deletes the specified API key.'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --location --globoff --request DELETE \"https://api.us.nylas.com/v3/admin/applications/<NYLAS_APPLICATION_ID>/api-keys/<API_KEY_ID>\" \\\n  --header \"Content-Type: application/json\" \\\n  --header \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n  --header \"X-Nylas-Nonce: <NONCE>\" \\\n  --header \"X-Nylas-Timestamp: 1676412353123\" \\\n  --header \"X-Nylas-Signature: <BASE64_SIGNATURE>\""
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    description: ID of the request.
              examples:
                OK:
                  value:
                    request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
components:
  responses:
    get-api-keys-200:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              data:
                type: array
                items:
                  type: object
                  description: An API key. The secret key value is not returned when listing keys.
                  properties:
                    application_id:
                      type: string
                      description: The ID of the application the API key is associated with.
                    created_at:
                      type: number
                      description: When the API key was created, in seconds using the Unix timestamp format.
                    expires_at:
                      type: number
                      description: When the API key will expire, in seconds using the Unix timestamp format.
                    expires_in:
                      type: number
                      description: How long the API key is valid, in seconds.
                    id:
                      type: string
                      description: The API key ID.
                    name:
                      type: string
                      description: The name of the API key.
                    permissions:
                      type: array
                      description: An array of permissions associated with the API key.
                      items:
                        type: string
                    status:
                      type: string
                      description: The status of the API key.
                    updated_at:
                      type: number
                      description: When the API key was last updated, in seconds using the Unix timestamp format.
          example:
            request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
            data:
            - id: 5aa1d7a6-5b61-4e2c-8e1f-2c3a5d1b9f10
              application_id: ad410018-d306-43f9-8361-fa5d7b2172e0
              created_at: 1617817109
              expires_at: 1619385186
              expires_in: 3600
              name: Leyah's API key
              permissions:
              - all
              status: active
              updated_at: 1617817109
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The error from the provider.
          examples:
            Bad Request:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: invalid_request_error
                  message: error parsing request body
                  provider_error:
                    code: TargetIdShouldNotBeMeOrWhitespace
                    message: Id is malformed.
            Invalid Idempotency-Key:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: api.invalid_idempotency_key
                  message: Idempotency-Key must be 256 characters or fewer.
    '429':
      description: 'Rate limited. The provider or Nylas throttled the request. If a provider throttles a request and

        says how long to wait, the `Retry-After` header gives that number of seconds. When the header

        is missing, retry with exponential backoff. See

        [429 rate limit errors by provider](/docs/api/errors/400-response/#429-rate-limit-errors-by-provider).'
      headers:
        Retry-After:
          description: 'The number of seconds to wait before retrying, rounded up. Present only when the provider, or

            Nylas for an Agent Account send, said how long to wait.'
          schema:
            type: integer
            example: 30
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The provider's own error, when the provider returned one.
          examples:
            Rate limited:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: rate_limit_error
                  message: Too many requests. If you see this error when fetching objects, set your limit=20 or lower. See http://nyl.as/429-tmr.
    get-api-key-200:
      description: OK
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/common_response'
            - properties:
                data:
                  type: object
                  properties:
                    application_id:
                      type: string
                      description: The ID of the application the API key is associated with.
                    created_at:
                      type: number
                      description: When the API key was created, in seconds using the Unix timestamp format.
                    expires_at:
                      type: number
                      description: When the API key will expire, in seconds using the Unix timestamp format.
                    expires_in:
                      type: number
                      description: How long the API key is valid, in seconds.
                    id:
                      type: string
                      description: The API key ID.
                    name:
                      type: string
                      description: The name of the API key.
                    permissions:
                      type: array
                      description: An array of permissions associated with the API key.
                      items:
                        type: string
                    status:
                      type: string
                      description: The status of the API key.
                    updated_at:
                      type: number
                      description: When the API key was last updated, in seconds using the Unix timestamp format.
          example:
            request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
            data:
              application_id: ad410018-d306-43f9-8361-fa5d7b2172e0
              created_at: 1617817109
              expires_at: 1619385186
              expires_in: 3600
              name: Leyah's API key
              permissions:
              - all
              status: active
              updated_at: 1617817109
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The error from the provider.
          examples:
            Unauthorized:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: unauthorized
                  message: Unauthorized
                  provider_error:
                    code: 401
                    message: Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
  schemas:
    common_response:
      properties:
        request_id:
          type: string
          description: The request ID.
        data:
          type: object
          description: The response object.
      example:
        request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
  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)