Service accounts

A service account is a machine identity in your workspace. Your pipelines, the GitHub Action and your scripts use it to call the Vulnara API without anyone signing in. It has a name and a secret token, and it expires on a date you choose.

What it is for

• Running the GitHub Action in your CI.
• Running the CLI on a build server or in a container.
• Calling the GraphQL API from your own scripts.

Using a service account keeps a person's credentials out of your CI, and lets you cut off one pipeline without touching anyone's login.

How it works

A service account belongs to one workspace. Its full name is the workspace name in lower case, with spaces turned into underscores, followed by an underscore and the name you gave it: a service account called ci in the workspace Acme Corp is acme_corp_ci. The list shows this full name, and it is what you pass as the username.

To call Vulnara, a tool exchanges the name and the token for a short-lived access token, then sends that with each request. The GitHub Action and the CLI do this for you.

What you can set

• Name: 2 to 50 characters. It must be unique in the workspace.
• Expires At: the date the token stops working. It defaults to 30 days from now and can be at most one year away.
• Active: whether the account can be used. You can switch it off and on again.

Do it

Create a service account

1. In the sidebar, go to Access & Security, then Service Accounts.
2. Choose Create Service Account.
3. Enter a Name, pick Expires At, and submit.
4. Copy the secret that is shown and store it somewhere safe, such as your CI's secret store.
5. Confirm that you have stored it. Only then can you close the dialog.

API: createServiceAccount. CLI: create_service_account. The token is in the response of the create call and nowhere else.

Deactivate or activate a service account

Flip the account's Active switch, or select accounts and choose Deactivate or Activate. A deactivated account cannot be used to reach the API until you activate it again. API: setServiceAccountActive. CLI: set_service_account_active.

Delete a service account

Choose Delete on the account and confirm. Its token stops working and the account cannot be restored. API: deleteServiceAccount. CLI: delete_service_account.

Keep track of expiry

The header of the Service Accounts screen counts active, inactive and expiring accounts. Choose a figure to filter the list by it. Expiring soon covers active accounts that expire within 7 days or have already expired. Create a replacement before an account expires, update your CI secret, then delete the old one.

Good to know

• Admins only: creating, activating, deactivating and deleting service accounts needs the admin role. Everyone in the workspace can see the list. See Teams and roles.
• A service account is read-only: it holds the viewer role in its workspace. It can read everything a viewer can, and it cannot make changes such as deleting repositories.
• Not a team member: service accounts do not appear on the Team screen, and do not count as users.
• Duplicate names are refused: "A service account with the same name already exists."
• Created by: each account shows who created it.
• One workspace each: a service account works only in the workspace it was created in. Create one per workspace you automate.