> ## 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.

# 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](/docs/astro-private-cloud/v-1-x/role-permission-reference).

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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save the API key">
    Copy the API key that appears and store it in an environment variable or secrets management tool.

    <Note>The API key appears only once. Store it securely before you leave the page.</Note>
  </Step>
</Steps>

## Create a service account with the Astro CLI

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

<Tabs>
  <Tab title="Workspace">
    1. Get your Workspace ID:

       ```bash theme={null}
       astro workspace list
       ```

    2. Create the service account:

       ```bash theme={null}
       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`.
  </Tab>

  <Tab title="Deployment">
    1. Get your Deployment ID:

       ```bash theme={null}
       astro deployment list
       ```

    2. Create the service account:

       ```bash theme={null}
       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`.
  </Tab>
</Tabs>

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](/docs/astro-private-cloud/v-1-x/houston-api-authenticate).

<Tabs>
  <Tab title="System">
    ```graphql theme={null}
    mutation {
      createSystemServiceAccount(
        label: "<service-account-label>"
        role: SYSTEM_ADMIN
      ) {
        id
        apiKey
      }
    }
    ```
  </Tab>

  <Tab title="Workspace">
    ```graphql theme={null}
    mutation {
      createWorkspaceServiceAccount(
        workspaceUuid: "<workspace-id>"
        label: "<service-account-label>"
        role: WORKSPACE_ADMIN
      ) {
        id
        apiKey
      }
    }
    ```
  </Tab>

  <Tab title="Deployment">
    ```graphql theme={null}
    mutation {
      createDeploymentServiceAccount(
        deploymentUuid: "<deployment-id>"
        label: "<service-account-label>"
        role: DEPLOYMENT_ADMIN
      ) {
        id
        apiKey
      }
    }
    ```
  </Tab>
</Tabs>

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](/docs/astro-private-cloud/v-1-x/houston-api-develop-test).

## 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](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html). 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:

```text theme={null}
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](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html#operation/post_dag_run):

<CodeGroup>
  ```bash title="cURL" theme={null}
  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 '{}'
  ```

  ```python title="Python" theme={null}
  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())
  ```
</CodeGroup>

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.