Create a service account

A service account is a non-user identity that authenticates automated processes, such as CI/CD pipelines, with Astro Private Cloud. Each service account generates a permanent API key that assumes a user role and its set of permissions. Any request made with the API key has the same permissions as the role you assign to the service account. Use service accounts instead of personal user credentials for automation, so that automated processes keep working when individual users leave or change roles.

Service account levels

You can create service accounts at three levels. The level determines the scope of the actions the service account can perform.

Level	Scope	Available roles	Example use case
System	The entire Astro Private Cloud installation.	`SYSTEM_VIEWER`, `SYSTEM_EDITOR`, `SYSTEM_ADMIN`	Platform-wide automation that manages multiple Workspaces or Deployments.
Workspace	A single Workspace and all of its Deployments.	`WORKSPACE_VIEWER`, `WORKSPACE_EDITOR`, `WORKSPACE_ADMIN`	Deploying code to any Deployment in a Workspace with one API key.
Deployment	A single Deployment.	`DEPLOYMENT_VIEWER`, `DEPLOYMENT_EDITOR`, `DEPLOYMENT_ADMIN`	Restricting a CI/CD pipeline to deploy to only one Deployment.

To deploy code, a service account must have an Editor or Admin role at its level. For a complete breakdown of roles and permissions, see User roles and permissions. You can create Workspace-level and Deployment-level service accounts using the Astro Private Cloud UI, the Astro CLI, or the Houston API. You can create system-level service accounts only with the Houston API.

Create a service account with the Astro Private Cloud UI

Use the Astro Private Cloud UI to create Workspace-level or Deployment-level service accounts.

Open the Service Accounts tab

For a Workspace-level service account, go to Workspace Settings > Service Accounts. For a Deployment-level service account, select a Deployment and then open its Service Accounts tab.

Create the service account

Select New Service Account and complete the following fields:

Name: A meaningful name for the service account.
Category: Optional. A category or description that helps you locate and sort service accounts.
User Role: The role that determines the service account’s permissions. To deploy code, select an Editor or Admin role.

Save the API key

Copy the API key that appears and store it in an environment variable or secrets management tool.

The API key appears only once. Store it securely before you leave the page.

Create a service account with the Astro CLI

Use the Astro CLI to create Workspace-level or Deployment-level service accounts.

Workspace
Deployment

Get your Workspace ID:
astro workspace list

Create the service account:

astro workspace service-account create --workspace-id=<workspace-id> --label=<service-account-label> --role=<workspace-role>

Set --role to WORKSPACE_VIEWER, WORKSPACE_EDITOR, or WORKSPACE_ADMIN. The default is WORKSPACE_VIEWER.

Get your Deployment ID:
astro deployment list

Create the service account:

astro deployment service-account create --deployment-id=<deployment-id> --label=<service-account-label> --role=<deployment-role>

Set --role to viewer, editor, or admin. The default is viewer.

Save the API key that the command returns in an environment variable or secrets management tool.

Create a service account with the Houston API

Use the Houston API to create service accounts at any level. Creating a system-level service account requires the Houston API. Before you run a mutation, authenticate your request as described in Authenticate to the Houston API.

System
Workspace
Deployment

mutation {
  createSystemServiceAccount(
    label: "<service-account-label>"
    role: SYSTEM_ADMIN
  ) {
    id
    apiKey
  }
}

mutation {
  createWorkspaceServiceAccount(
    workspaceUuid: "<workspace-id>"
    label: "<service-account-label>"
    role: WORKSPACE_ADMIN
  ) {
    id
    apiKey
  }
}

mutation {
  createDeploymentServiceAccount(
    deploymentUuid: "<deployment-id>"
    label: "<service-account-label>"
    role: DEPLOYMENT_ADMIN
  ) {
    id
    apiKey
  }
}

Save the returned apiKey value in a secure place, because it isn’t displayed again. To explore the full Houston API schema and test mutations interactively, see Develop and test queries.

Example: Use a service account with the Airflow REST API

After you create a service account, you can use its API key to authenticate requests to the Airflow REST API. This is one common way to leverage a service account, for example to trigger Dag runs from an external system without accessing the Airflow UI directly. Create a Deployment-level service account with an Editor or Admin role, then send requests to the following base URL:

https://deployments.<base-domain>/<deployment-release-name>/airflow/api/v1

Replace the following values with your own:

<base-domain>: The base domain of your Astro Private Cloud installation. For example, astronomer.example.com.
<deployment-release-name>: The release name of your Deployment. For example, galactic-stars-1234.
<api-key>: The API key for your Deployment-level service account.
<dag-id>: The name of your Dag (case-sensitive).

For example, to trigger a Dag run, send a POST request to the dagRuns endpoint:

curl -v -X POST https://deployments.<base-domain>/<deployment-release-name>/airflow/api/v1/dags/<dag-id>/dagRuns \
  -H 'Authorization: <api-key>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' -d '{}'

import requests

token = "<api-key>"
base_domain = "<base-domain>"
deployment_name = "<deployment-release-name>"
resp = requests.post(
    url=f"https://deployments.{base_domain}/{deployment_name}/airflow/api/v1/dags/example_dag/dagRuns",
    headers={"Authorization": token, "Content-Type": "application/json"},
    data='{}'
)
print(resp.json())

This request triggers a Dag run for the specified Dag, which is equivalent to manually triggering the Dag in the Airflow UI. Every request has the same permissions as the role of the service account you use.

Overview

Architecture

Upgrade to Astro Private Cloud

Install Astro Private Cloud

Develop Dags

Airflow administration

Airflow 3

Deploy Dags

Manage Deployments

Platform administration

Manage Platform resources

Security and compliance

Houston API

Platform Observability

Release notes

Version compatibility

Reference

Create a service account

Service account levels

Create a service account with the Astro Private Cloud UI

Create a service account with the Astro CLI

Create a service account with the Houston API

Example: Use a service account with the Airflow REST API

​Service account levels

​Create a service account with the Astro Private Cloud UI

​Create a service account with the Astro CLI

​Create a service account with the Houston API

​Example: Use a service account with the Airflow REST API

Service account levels

Create a service account with the Astro Private Cloud UI

Create a service account with the Astro CLI

Create a service account with the Houston API

Example: Use a service account with the Airflow REST API