Skip to main content

IAM API reference

Use the following reference to learn about all of the possible requests within the Identity and Access Management (IAM) schema.

tip

To use this schema in Postman:

  1. Click the Download button on this page to download the YAML file for the schema.
  2. Follow the Postman documentation to import the schema to Postman.
API docs by Redocly

Astro Identity and Access Management (IAM) API (v1beta1)

Download OpenAPI specification:Download

Astro Identity and Access Management (IAM) API

User

The user object represents a user account in your Astro Organization. Astro creates a new user object whenever you invite a user by email or add a user to Astro through an identity provider. The object contains all information about a user, including their personal information, roles, and login attempts. It doesn't include attributes for actions that the user completes after they log in, such as updating a Deployment. Make requests to user endpoints to manage permissions for existing users both at the Organization and Workspace level. To create new users, make requests to invite endpoints instead.

List users in an Organization

List users in an Organization or a specific Workspace within an Organization.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to list users for.

query Parameters
workspaceId
string

The ID of the Workspace to filter the list of users for. When specified, the API returns only users belonging to the specified Workspace.

offset
integer >= 0
Default: 0

Offset for pagination

limit
integer [ 0 .. 1000 ]
Default: 20

Limit for pagination

sorts
Array of strings
Items Enum: "id:asc" "id:desc" "username:asc" "username:desc" "fullName:asc" "fullName:desc" "createdAt:asc" "createdAt:desc" "updatedAt:asc" "updatedAt:desc"

Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'

Responses

Response samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "totalCount": 100,
  • "users": [
    ]
}

Get user information

Retrieve user information about a specific user account.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to which the user belongs.

userId
required
string

The user's ID.

Responses

Response samples

Content type
application/json
{
  • "avatarUrl": "https://avatar.url",
  • "createdAt": "2022-11-22T04:37:12Z",
  • "fullName": "Jane Doe",
  • "id": "clm9sq6s0000008kz7uvl7yz7",
  • "organizationRole": "ORGANIZATION_MEMBER",
  • "status": "ACTIVE",
  • "updatedAt": "2022-11-22T04:37:12Z",
  • "username": "user1@company.com",
  • "workspaceRoles": [
    ]
}

Update a user's roles

Update Organization and Workspace roles for a user.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to which the user belongs.

userId
required
string

The user's ID

Request Body schema: */*

The request body for updating the user's roles

organizationRole
string
Enum: "ORGANIZATION_OWNER" "ORGANIZATION_BILLING_ADMIN" "ORGANIZATION_MEMBER"

The user's updated Organization role.

Array of objects (WorkspaceRole)

The user's updated Workspace roles. Requires also specifying an OrganizationRole.

Responses

Response samples

Content type
application/json
{
  • "deploymentRoles": [
    ],
  • "organizationRole": "ORGANIZATION_OWNER",
  • "workspaceRoles": [
    ]
}

Team

The team object represents an Astro Team, which is a group of users that share the same permissions across your Organization and Workspaces. Make requests to team endpoints to create, update, and delete Teams across an Organization. See Configure Teams on Astro.

List Teams

List all Teams in an Organization.

Authorizations:
JWT
path Parameters
organizationId
required
string

ID of the Organization to list Teams for.

query Parameters
offset
integer >= 0
Default: 0

Offset for pagination

limit
integer [ 0 .. 1000 ]
Default: 20

Limit for pagination

sorts
Array of strings
Items Enum: "name:asc" "name:desc" "description:asc" "description:desc" "createdAt:asc" "createdAt:desc" "updatedAt:asc" "updatedAt:desc"

Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'

Responses

Response samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "teams": [
    ],
  • "totalCount": 100
}

Create a Team

Create a Team in an Organization. A Team is a group of users that have the same set of permissions in an Organization or Workspace.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization where the Team is created.

Request Body schema: application/json

The request body for creating a Team.

description
string

The Team's description.

memberIds
Array of strings

The list of IDs for users to add to the Team.

name
required
string

The Team's name.

organizationRole
string
Enum: "ORGANIZATION_OWNER" "ORGANIZATION_BILLING_ADMIN" "ORGANIZATION_MEMBER"

The Team's Organization role.

Responses

Request samples

Content type
application/json
{
  • "description": "My Team description",
  • "memberIds": [
    ],
  • "name": "My Team",
  • "organizationRole": "ORGANIZATION_MEMBER"
}

Response samples

Content type
application/json
{
  • "createdAt": "2022-11-22T04:37:12Z",
  • "createdBy": {
    },
  • "description": "My Team description",
  • "id": "clma5ftgk000008mhgev00k7d",
  • "isIdpManaged": false,
  • "name": "My Team",
  • "organizationId": "clma5g8q6000108mh88g27k1y",
  • "organizationRole": "ORGANIZATION_MEMBER",
  • "rolesCount": 1,
  • "updatedAt": "2022-11-22T04:37:12Z",
  • "updatedBy": {
    },
  • "workspaceRoles": [
    ]
}

Delete a Team

Delete a Team. Deleting a Team will remove all permissions associated with the Team. Users that previously belonged to the Team will no longer have these permissions.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to delete the Team from.

teamId
required
string

The ID of the Team to delete.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "requestId": "string",
  • "statusCode": 400
}

Get a Team

Retrieve details about a specific Team.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to which the Team belongs.

teamId
required
string

The ID of the Team to retrieve data for.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2022-11-22T04:37:12Z",
  • "createdBy": {
    },
  • "description": "My Team description",
  • "id": "clma5ftgk000008mhgev00k7d",
  • "isIdpManaged": false,
  • "name": "My Team",
  • "organizationId": "clma5g8q6000108mh88g27k1y",
  • "organizationRole": "ORGANIZATION_MEMBER",
  • "rolesCount": 1,
  • "updatedAt": "2022-11-22T04:37:12Z",
  • "updatedBy": {
    },
  • "workspaceRoles": [
    ]
}

Update a Team

Update a Team's details.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to which the Team belongs.

teamId
required
string

The ID of the Team to update.

Request Body schema: application/json

The request body for updating the Team.

description
string

The Team's description.

name
required
string

The Team's name.

Responses

Request samples

Content type
application/json
{
  • "description": "My Team Description",
  • "name": "My Team"
}

Response samples

Content type
application/json
{
  • "createdAt": "2022-11-22T04:37:12Z",
  • "createdBy": {
    },
  • "description": "My Team description",
  • "id": "clma5ftgk000008mhgev00k7d",
  • "isIdpManaged": false,
  • "name": "My Team",
  • "organizationId": "clma5g8q6000108mh88g27k1y",
  • "organizationRole": "ORGANIZATION_MEMBER",
  • "rolesCount": 1,
  • "updatedAt": "2022-11-22T04:37:12Z",
  • "updatedBy": {
    },
  • "workspaceRoles": [
    ]
}

List Team members

List the details about all users that belong to a specific Team.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to which the Team belongs.

teamId
required
string

The ID of the Team to retrieve member information for.

query Parameters
offset
integer >= 0
Default: 0

Offset for pagination

limit
integer >= 0
Default: 20

Limit for pagination

sorts
Array of strings
Items Enum: "userId:asc" "userId:desc" "fullName:asc" "fullName:desc" "username:asc" "username:desc" "createdAt:asc" "createdAt:desc"

Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'

Responses

Response samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "teamMembers": [
    ],
  • "totalCount": 100
}

Add members to a team

Add members to a team

Authorizations:
JWT
path Parameters
organizationId
required
string

organization ID

teamId
required
string

team ID

Request Body schema: application/json

request body for adding members to a team

memberIds
required
Array of strings non-empty

The list of IDs for users to add to the Team.

Responses

Request samples

Content type
application/json
{
  • "memberIds": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "requestId": "string",
  • "statusCode": 400
}

Remove Team member

Remove a user from a Team. The user loses all permissions associated with the Team.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to which the user belongs.

teamId
required
string

The ID of the Team to remove the user from.

memberId
required
string

The ID of the user to remove.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "requestId": "string",
  • "statusCode": 400
}

Update Team roles

Update Organization and Workspace roles for a Team.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to which the Team belongs.

teamId
required
string

The ID of the Team to update roles for.

Request Body schema: application/json

The request body for updating the Team's roles

organizationRole
required
string
Enum: "ORGANIZATION_OWNER" "ORGANIZATION_BILLING_ADMIN" "ORGANIZATION_MEMBER"

The Team's Organization roles.

Array of objects (WorkspaceRole)

The Team's updated Workspace roles. The Workspaces you specify must belong to the Team's Organization.

Responses

Request samples

Content type
application/json
{
  • "organizationRole": "ORGANIZATION_MEMBER",
  • "workspaceRoles": [
    ]
}

Response samples

Content type
application/json
{
  • "deploymentRoles": [
    ],
  • "organizationRole": "ORGANIZATION_OWNER",
  • "workspaceRoles": [
    ]
}

ApiToken

The apitoken object represents a single API token within your Organization. API tokens are used to authenticate automated tools and processes to your Organization. They have varying levels of access to your resources based on their Organization, Workspace, and Deployment roles. See [Workspace API tokens])(workspace-api-tokens.md) and Organization API tokens.

List API tokens

List information about all API tokens from an Organization. Filters on Workspace when Workspace ID is provided. When includeOnlyOrganizationTokens is true, only Organization API tokens are returned.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to list tokens for.

query Parameters
workspaceId
string

The ID of the Workspace to list API tokens for.

deploymentId
string

The ID of the Deployment to list API tokens for.

includeOnlyOrganizationTokens
boolean

Whether to show only Organization API tokens.

offset
integer >= 0
Default: 0

Offset for pagination

limit
integer [ 0 .. 1000 ]
Default: 20

Limit for pagination

sorts
Array of strings
Items Enum: "name:asc" "name:desc" "description:asc" "description:desc" "createdAt:asc" "createdAt:desc" "updatedAt:asc" "updatedAt:desc" "tokenStartAt:asc" "tokenStartAt:desc"

Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'

Responses

Response samples

Content type
application/json
{
  • "limit": 10,
  • "offset": 0,
  • "tokens": [
    ],
  • "totalCount": 100
}

Create an API token

Create an API token. An API token is an alphanumeric token that grants programmatic access to Astro for automated workflows. An API token can be scoped to an Organization or a Workspace.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization where you want to create the token.

Request Body schema: application/json

The Request body for creating an API token

description
string

The description for the API token.

entityId
string

The ID of the Workspace or Deployment to which the API token is scoped. It is required if Type is WORKSPACE or DEPLOYMENT.

name
required
string

The name of the API token.

role
required
string
Enum: "DEPLOYMENT_ADMIN" "WORKSPACE_OWNER" "WORKSPACE_OPERATOR" "WORKSPACE_AUTHOR" "WORKSPACE_MEMBER" "ORGANIZATION_OWNER" "ORGANIZATION_BILLING_ADMIN" "ORGANIZATION_MEMBER"

The role of the API token.

tokenExpiryPeriodInDays
integer [ 1 .. 3650 ]

The expiry period of the API token in days. If not specified, the token will never expire.

type
required
string
Enum: "DEPLOYMENT" "WORKSPACE" "ORGANIZATION"

The scope of the API token.

Responses

Request samples

Content type
application/json
{
  • "description": "This is my API token",
  • "entityId": "clm8pxjjw000008l23jm08hyu",
  • "name": "My token",
  • "role": "WORKSPACE_OWNER",
  • "tokenExpiryPeriodInDays": 30,
  • "type": "WORKSPACE"
}

Response samples

Content type
application/json
{
  • "createdAt": "2022-11-22T04:37:12Z",
  • "createdBy": {
    },
  • "description": "my token description",
  • "endAt": "2022-11-22T04:37:12Z",
  • "expiryPeriodInDays": 30,
  • "id": "clm8q7f6q000008lcgyougpsk",
  • "lastUsedAt": "2022-11-22T04:37:12Z",
  • "name": "My token",
  • "roles": [
    ],
  • "shortToken": "short-token",
  • "startAt": "2022-11-22T04:37:12Z",
  • "token": "token",
  • "type": "WORKSPACE",
  • "updatedAt": "2022-11-22T04:37:12Z",
  • "updatedBy": {
    }
}

Delete an API token

Delete an API token. When you delete an API token, make sure that no existing automation workflows are using it. After it's deleted, an API token cannot be recovered.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization where you want to delete the token.

tokenId
required
string

The API token ID

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "requestId": "string",
  • "statusCode": 400
}

Get an API token

Retrieve information about a specific API token.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization where you want to retrieve token information.

tokenId
required
string

The ID of the token that you want to retrieve data for.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2022-11-22T04:37:12Z",
  • "createdBy": {
    },
  • "description": "my token description",
  • "endAt": "2022-11-22T04:37:12Z",
  • "expiryPeriodInDays": 30,
  • "id": "clm8q7f6q000008lcgyougpsk",
  • "lastUsedAt": "2022-11-22T04:37:12Z",
  • "name": "My token",
  • "roles": [
    ],
  • "shortToken": "short-token",
  • "startAt": "2022-11-22T04:37:12Z",
  • "token": "token",
  • "type": "WORKSPACE",
  • "updatedAt": "2022-11-22T04:37:12Z",
  • "updatedBy": {
    }
}

Update an API token

Update the name and description of an API token.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization where you want to update an API token.

tokenId
required
string

The API token you want to update.

Request Body schema: application/json

The request body for updating a token.

description
string <= 500 characters

The description of the API token.

name
required
string [ 1 .. 256 ] characters

The name of the API token.

Responses

Request samples

Content type
application/json
{
  • "description": "This is my API token",
  • "name": "My token"
}

Response samples

Content type
application/json
{
  • "createdAt": "2022-11-22T04:37:12Z",
  • "createdBy": {
    },
  • "description": "my token description",
  • "endAt": "2022-11-22T04:37:12Z",
  • "expiryPeriodInDays": 30,
  • "id": "clm8q7f6q000008lcgyougpsk",
  • "lastUsedAt": "2022-11-22T04:37:12Z",
  • "name": "My token",
  • "roles": [
    ],
  • "shortToken": "short-token",
  • "startAt": "2022-11-22T04:37:12Z",
  • "token": "token",
  • "type": "WORKSPACE",
  • "updatedAt": "2022-11-22T04:37:12Z",
  • "updatedBy": {
    }
}

Update API token roles

Update Workspace and Organization roles for an API token.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization where you want to update an API token.

tokenId
required
string

The API token you want to update.

Request Body schema: application/json

The request body for updating a token.

required
Array of objects (ApiTokenRole) non-empty

The roles of the API token.

Array (non-empty)
entityId
required
string

The ID of the entity to which the API token is scoped for. For example, for Workspace API tokens, this is the Workspace ID.

entityType
required
string
Enum: "DEPLOYMENT" "WORKSPACE" "ORGANIZATION"

The type of the entity to which the API token is scoped for.

role
required
string
Enum: "DEPLOYMENT_ADMIN" "WORKSPACE_OWNER" "WORKSPACE_OPERATOR" "WORKSPACE_AUTHOR" "WORKSPACE_MEMBER" "ORGANIZATION_OWNER" "ORGANIZATION_BILLING_ADMIN" "ORGANIZATION_MEMBER"

The role of the API token.

Responses

Request samples

Content type
application/json
{
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "deploymentRoles": [
    ],
  • "organizationRole": "ORGANIZATION_OWNER",
  • "workspaceRoles": [
    ]
}

Rotate API token

Rotate an API token. Creates a new API token and invalidates the one you specify. Any workflows using the previous value stop working.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization where you want to rotate an API token.

tokenId
required
string

The token to rotate

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2022-11-22T04:37:12Z",
  • "createdBy": {
    },
  • "description": "my token description",
  • "endAt": "2022-11-22T04:37:12Z",
  • "expiryPeriodInDays": 30,
  • "id": "clm8q7f6q000008lcgyougpsk",
  • "lastUsedAt": "2022-11-22T04:37:12Z",
  • "name": "My token",
  • "roles": [
    ],
  • "shortToken": "short-token",
  • "startAt": "2022-11-22T04:37:12Z",
  • "token": "token",
  • "type": "WORKSPACE",
  • "updatedAt": "2022-11-22T04:37:12Z",
  • "updatedBy": {
    }
}

Invite

The invite object represents the record of a user invite generated by Astro. It includes information both about the inviter and the invitee. Invites can be generated both by manual invitations through the Cloud UI and automatic invitations through an identity provider. An invite record persists until its associated invite expires. Make requests to invite endpoints to create, delete, or audit invites for users across your Organization. See Manage Organization users and Manage Workspace users.

Create a user invitation

Invite a user to an Organization.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization to invite the user to.

Request Body schema: application/json

The request body for creating user invite.

inviteeEmail
required
string

The email of the user to invite.

role
required
string
Enum: "ORGANIZATION_OWNER" "ORGANIZATION_BILLING_ADMIN" "ORGANIZATION_MEMBER"

The user's Organization role.

Responses

Request samples

Content type
application/json
{
  • "inviteeEmail": "user1@company.com",
  • "role": "ORGANIZATION_MEMBER"
}

Response samples

Content type
application/json
{
  • "expiresAt": "2022-11-22T04:37:12Z",
  • "inviteId": "clm9t1g17000008jmfsw20lsz",
  • "invitee": {
    },
  • "inviter": {
    },
  • "organizationId": "clm9t0gbt000108jv4f1cfu8u",
  • "organizationName": "My Organization",
  • "userId": "clm9t060z000008jv3mira7x5"
}

Delete a user invite

Delete an existing user invite.

Authorizations:
JWT
path Parameters
organizationId
required
string

The ID of the Organization where the user was invited to.

inviteId
required
string

The invite's ID.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "requestId": "string",
  • "statusCode": 400
}

Was this page helpful?

Sign up for Developer Updates

Get a summary of new Astro features once a month.

You can unsubscribe at any time.
By proceeding you agree to our Privacy Policy, our Website Terms and to receive emails from Astronomer.