Skip to main content
Version: Enterprise Edition v1.5 (latest)

Service Accounts

A service account allows you to programmatically access the API.

Overview​

Service accounts are special users that can only be used to consume the Semaphore API. Service accounts cannot be used to log in to the Semaphore UI.

Service accounts share the same role-based authentication control model used for regular Semaphore users.

How to create a service account​

To create a service account, follow these steps:

  1. Open the Server Menu on the top-right corner

  2. Select People

  3. Press Create Service Account

    Create service account button

  4. Define the service account name (1), an optional description (2), and assign a role (3). Press Create Service Account (4) when ready

    Service account creation modal

  5. Take note of the API token, as it can only be viewed once. Press Done when ready

    Service account token reveal

How to use a service account​

Service accounts' tokens are used in the same way as regular user tokens. The service account token must be supplied in every call to the Semaphore API.

For example, to retrieve logs for a job, you can use the service account token in the following way:


API_TOKEN=<YOUR_SERVICE_ACCOUNT_TOKEN_HERE>
curl -H "Authorization: Token ${API_TOKEN}" "https://<semaphore-server-url>/api/v1alpha/logs/11493d45-6088-44ef-acef-ab12bf778505"

How to edit service account​

To edit a service account's details, follow these steps:

  1. Open the Server Menu on the top-right corner

  2. Select People

  3. Press the Edit button next to the service account you want to edit

    Create service account button

  4. You can change the service account name, description, and role

  5. Press Save changes when done

How to reset a service account token​

Once viewed, the token of a service account cannot be retrieved again. If you lost the token connected to a service account, your only option is to regenerate a new token.

warning

Resetting the token will revoke access to any applications that are currently using the service account.

To reset a service account token, follow these steps.

  1. Open the Server Menu on the top-right corner

  2. Select People

  3. Press the Refresh button next to the service account you want to reset

    Create service account button

  4. Press Regenerate Token

  5. Copy the new token and save it in a safe place

How to delete a service account​

warning

Deleting a service account will revoke access to any applications that are currently using it.

To delete a service account, follow these steps.

  1. Open the Server Menu on the top-right corner

  2. Select People

  3. Press the red X (cross) button next to the service account you want to delete

    Create service account button

  4. Press Delete Service Account

See also​