Skip to main content

Service accounts

A service account is a login for automation, not for a person. CI pipelines, scripts and SDK code sign in with one of its API keys and act with its role. Because it belongs to the organization rather than to someone's account, it keeps working when people join, change role or leave.

Use a service account for anything that runs without a person: a deploy pipeline, a scheduled job, a bot. Use your own API key for your own terminal.

Before you start​

  • An organization owner or admin. Other members don't see service accounts.
  • The smallest role the integration needs (see Roles).

In the console​

  1. Open Service Accounts in the sidebar and select Create service account.

  2. Enter a Name (for example deploy-pipeline), pick a Role, and add a Description that says what uses it, for example "GitHub Actions deploys to production".

    Open zoom view

    Create service account with a name, a role and a description

    Create service account with a name, a role and a descriptionCreate service account with a name, a role and a description

  3. On Create its first key, name the key (optional, for example deploy) and pick Expires after: 1 hour to 90 days, with 30 days (default), or Never expires. Select Create key.

  4. Copy the key into your CI secret store. It is shown once.

You should see​

The account under Active with its role. Open it to see its keys, each with its status and when it expires; Create key adds another, and each key's actions revoke it. Edit changes the name, description or role. Archive retires the account.

Roles​

  • Viewer: Read organization resources.
  • Editor: Viewer, plus deploy, update and resync applications.
  • Admin: Editor, plus clusters, add-ons and application profiles, and deleting applications.

A service account can't delete a cluster (that needs the organization's owner), own an organization, manage members, issue service-account keys or use global administration. A role change applies to the account's keys on their next request.

Use the key​

Set ASTROPULSE_API_KEY to the key in your integration's secret configuration. astroctl and the SDK read it; direct requests send it in the X-Astro-API-Key header. The key carries its organization, so it needs no org use, and no header can widen it to another organization.

How service account keys are kept safe​

  • A key is shown once, when it is created. The account page shows only its name, status and expiry.
  • Anyone who holds a key acts with the account's role. Keep it out of source control, logs and browser code.
  • A key stays active until it expires or is revoked, even after the person who created it leaves: give it an expiry, and rotate it.
  • What a person does to an account or its keys is in the audit log under that person; what the automation does is under the service account's own name.

Rotate or retire​

To rotate, create a new key, switch the integration to it, check a request succeeds, then revoke the old key. Both keys work during the overlap, so nothing stops.

Archive stops every key of the account on its next request and cannot be undone: "Every key of this account stops working. Archiving cannot be undone." Create a new account if the integration needs access again.

Personal and service account keys share the organization's API key limit: 3 on Developer, 1,000 by default on Enterprise, which can be changed for your organization. Expired keys, revoked keys and archived accounts' keys free their places.

Other ways in​

  • SDK: service_accounts.create_service_account and create_service_account_key in the Python SDK, authenticated with an admin's personal key. A key created without a duration lasts 24 hours.
  • API: the service accounts calls in the API reference.

With astroctl​

Terminal
astroctl org service-account create --name ci --role Editor
astroctl org service-account keys create ci --duration 720h
astroctl org service-account keys list ci

Every flag: astroctl org service-account.

If it's refused​

A refused service account key is answered with HTTP 401 and one of these.

"The API key has expired. An organization admin can create a new key for this service account in the console under Organization settings › Service Accounts."
Cause
The key passed its expiry.
Fix
An owner or admin creates a new key on the account, and you update the integration's secret.
"The API key has been revoked. An organization admin can create a new key for this service account in the console under Organization settings › Service Accounts."
Cause
The key was revoked, or its account archived.
Fix
Create a new key on an active account.
"The API key is not valid. An organization admin can create a new key for this service account in the console under Organization settings › Service Accounts."
Cause
The key is not one AstroPulse issued.
Fix
Copy the key again from where it was stored, or create a new one.

Next​