> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# IAM API changelog

<Update label="2026-04-02">
  ## Summary

  * Added `kind` property to `ApiToken` and `CreateApiTokenRequest` schemas, allowing specification of token type.
  * Introduced new permissions for various API endpoints related to API tokens and user roles.
  * Modified query parameters for the `/organizations/{organizationId}/tokens` endpoint, including changes to pagination and sorting criteria.

  ## Added

  * **Schemas**
    * `ApiToken`
      * `kind`: Specifies the type of API token. Options are `STANDARD` and `DIRECT_ACCESS`.
    * `CreateApiTokenRequest`
      * `kind`: Specifies the type of API token, defaulting to `STANDARD`.

  * **Permissions**
    * `/organizations/{organizationId}/tokens`
      * `GET`, `POST`: Requires `organization.apiTokens.access`.
    * `/organizations/{organizationId}/tokens/{tokenId}`
      * `GET`, `POST`, `DELETE`: Requires `organization.apiTokens.access`.
    * `/organizations/{organizationId}/tokens/{tokenId}/roles`
      * `POST`: Requires `organization.apiTokens.access`.
    * `/organizations/{organizationId}/tokens/{tokenId}/rotate`
      * `POST`: Requires `organization.apiTokens.access`.
    * `/organizations/{organizationId}/users/{userId}/roles`
      * `POST`: Requires `organization.userRoles.access`.

  * **Query Parameters**
    * `/organizations/{organizationId}/tokens`
      * `sorts`: Sorting criteria for API tokens, with options like `name:asc`, `createdAt:desc`, etc.

  ## Changed

  * **Schemas**
    * `ApiToken`
      * `kind` is now a required property.

  * **Query Parameters**
    * `/organizations/{organizationId}/tokens`
      * `kind`: Replaced `offset` parameter. Now specifies the type of API token to list.
      * `offset`: Previously `limit`, now specifies pagination offset.
      * `limit`: Previously `sorts`, now specifies pagination limit with a default of 20 and a maximum of 1000.

  * **Parameter Descriptions**
    * Updated descriptions for `kind`, `offset`, and `limit` parameters to reflect their new purposes.
</Update>

<Update label="2025-09-17">
  ## Summary

  * Introduced new endpoints for managing Agent Tokens, including listing, creating, retrieving, and deleting tokens.
  * Added a new schema `CreateAgentTokenRequest` for creating Agent Tokens with properties such as `name`, `description`, and `tokenExpiryPeriodInDays`.

  ## Added

  * **Schemas**
    * `CreateAgentTokenRequest`
      * `name` (string): The name of the Agent token. Required.
      * `description` (string): The description for the Agent token.
      * `tokenExpiryPeriodInDays` (integer): The expiry period of the Agent token in days. Defaults to never expire if not specified. Range: `1` to `3650`.

  * **Endpoints**
    * `GET /organizations/{organizationId}/deployments/{deploymentId}/agent-tokens`
      * List Agent Tokens.
      * Parameters:
        * `organizationId` (path, string): The ID of the Organization.
        * `deploymentId` (path, string): The ID of the Deployment.
        * `offset` (query, integer): Number of results to skip. Default: `0`.
        * `limit` (query, integer): Maximum number of results to return. Default: `20`, Max: `1000`.
        * `sorts` (query, array of strings): Fields to sort by. For example, `name:asc`.
      * Responses: `200`, `400`, `401`, `403`, `404`, `500`.

    * `POST /organizations/{organizationId}/deployments/{deploymentId}/agent-tokens`
      * Create an Agent token.
      * Parameters:
        * `organizationId` (path, string): The ID of the Organization.
        * `deploymentId` (path, string): The ID of the Deployment.
      * Request Body: `CreateAgentTokenRequest`
      * Responses: `200`, `400`, `401`, `403`, `404`, `500`.

    * `GET /organizations/{organizationId}/deployments/{deploymentId}/agent-tokens/{agentTokenId}`
      * Retrieve an Agent Token.
      * Parameters:
        * `organizationId` (path, string): The ID of the Organization.
        * `deploymentId` (path, string): The ID of the Deployment.
        * `agentTokenId` (path, string): The ID of the Agent token.
      * Responses: `200`, `400`, `401`, `403`, `404`, `500`.

    * `DELETE /organizations/{organizationId}/deployments/{deploymentId}/agent-tokens/{agentTokenId}`
      * Delete an Agent Token.
      * Parameters:
        * `organizationId` (path, string): The ID of the Organization.
        * `deploymentId` (path, string): The ID of the Deployment.
        * `agentTokenId` (path, string): The ID of the Agent token.
      * Responses: `204`, `400`, `401`, `403`, `404`, `500`.

  ## Changed

  * No existing schemas or endpoints were modified.
</Update>

<Update label="2024-12-10">
  ## Summary

  Added new RBAC roles for [Preview Astro Observe](/docs/astro/create-data-products).

  ## Added

  Included the following new enums for defining Organization roles:

  * `ORGANIZATION_OBSERVE_ADMIN`
  * `ORGANIZATION_OBSERVE_MEMBER`
</Update>

<Update label="2024-07-31">
  ## Summary

  This update introduces new endpoints for managing IP access lists. See [Astro IP access list documentation](/docs/astro/ip-access-list) for more information.

  ### Added

  New endpoints:

  * `GET /organizations/{organizationId}/allowed-ip-address-ranges` to list allowed IP address ranges
  * `POST /organizations/{organizationId}/allowed-ip-address-ranges` to create an allowed IP address range that constrains which IP addresses can be used to interact with your Astro Organization using APIs
  * `DELETE /organizations/{organizationId}/allowed-ip-address-ranges/{allowedIpAddressRangeId}` to delete an allowed IP address range.

  New object schemas:

  * `CreateAllowedIpAddressRangeRequest`
  * `AllowedIpAddressRangesPaginated`
  * `AllowedIpAddressRange`
</Update>

<Update label="2024-04-12">
  * The endpoint `DELETE /organizations/{organizationId}/roles/{customRoleId}` now returns a
    `deploymentRoles` attribute
  * The endpoint `GET /authorization/permission-groups` now returns a
    `deploymentRoles` attribute
  * The endpoint `GET /organizations/{organizationId}/role-templates` now returns a
    `deploymentRoles` attribute
  * The endpoint `GET /organizations/{organizationId}/roles` now returns a
    `deploymentRoles` attribute
  * The endpoint `GET /organizations/{organizationId}/roles/{roleId}` now returns a
    `deploymentRoles` attribute
  * The endpoint `POST /organizations/{organizationId}/roles` now returns a
    `deploymentRoles` attribute
  * The endpoint `POST /organizations/{organizationId}/roles/{customRoleId}` now returns a
    `deploymentRoles` attribute
</Update>