Skip to main content

Service Accounts

A service account is a non-human principal in your Signadot organization, meant for automation such as CI pipelines, scripts, and integrations. It is a peer to a user: it belongs to the org, carries a role, and holds one or more API keys that authenticate requests to the Signadot API and CLI.

Unlike a user, a service account has no login, no email, and no SSO identity. It exists only to own API keys with a well-defined role, so automated access is attributable to a named account rather than to a person.

Why Use Service Accounts​

  • Attribution. Automated traffic is tied to a named account (for example ci-github-actions) instead of a person's key, so audit logs and usage are clear about who did what.
  • Least privilege. Each service account has its own role, so you can scope a pipeline to exactly the access it needs.
  • Lifecycle independent of people. Keys keep working when a teammate leaves the org, because they belong to the service account, not to a user.

Who Can Manage Service Accounts​

Only users with the admin role can create, edit, and delete service accounts and their API keys. See Role-Based Access Control for details on roles.

Anatomy of a Service Account​

FieldDescription
NameUnique identifier within the org. Must start with a lowercase letter and contain only lowercase letters, digits, hyphens, and underscores, up to 63 characters. Immutable once created.
DescriptionOptional human-readable note, up to 255 characters.
RoleAuthorization role: admin or member. Every API key the account holds inherits this role.

Roles​

A service account's role mirrors the user role model, and its API keys inherit the account's role:

  • admin grants full administrative access to the org.
  • member grants standard access to application-related entities (sandboxes, route groups, resource plugins), without administration functions.

Choose the narrowest role that lets the automation do its job. For example, a CI pipeline that only creates and deletes sandboxes should be a member. Use admin only when the automation also needs administration access (for example managing cluster tokens or organization secrets).

Creating a Service Account​

  1. Log in to the Signadot Dashboard.
  2. Navigate to Settings > Service Accounts.
  3. Click Create Service Account.
  4. Enter a name (see the naming rules above), an optional description, and a role.
  5. Create the account. It starts with no API keys.

Issuing an API Key​

An API key is what actually authenticates requests. A service account can hold more than one key, which is useful for rotation.

  1. Open the service account and go to its Keys tab.
  2. Click Create API Key and give it an optional description.
  3. Copy the key value immediately.
caution

API key values are only displayed once, at creation time. Signadot stores a hashed version and cannot retrieve the original value. Afterward, only a masked value is shown. If you lose a key, revoke it and create a new one.

Each key records a last-used timestamp, so you can spot keys that are no longer in use and revoke them.

Using a Service Account Key​

Provide the key to the Signadot CLI or API the same way as any Signadot API key. The most common approach in CI/CD is environment variables:

export SIGNADOT_ORG=<your-org>
export SIGNADOT_API_KEY=<the-key-value>
signadot sandbox list

Requests made with the key act with the service account's role. See API Keys for the full list of ways to supply a key (the signadot auth command, the signadot-api-key header for preview URLs and the REST API, and the CI/CD integration guides).

Rotating a Key​

To rotate without downtime:

  1. Issue a second key on the service account.
  2. Roll it out to your automation (update CI secrets, scripts).
  3. Confirm the new key's last-used timestamp is advancing.
  4. Revoke the old key.

Deleting a Service Account​

You cannot delete a service account while it still holds API keys. This safeguards against orphaning credentials that automation may still be using. Remove all of the account's keys from its Keys tab first, then delete the account.

Other resources the account owns (such as sandboxes and route groups) are left in place for an admin to clean up.

Legacy Organization Keys and the admin Service Account​

Historically, API keys were created at the organization level and were not attached to a named principal. Going forward, every API key belongs to a service account, so those keys need a home.

Pre-existing organization API keys are grouped under a single service account named admin, with the admin role, so they keep working exactly as before:

  • Your existing keys continue to function unchanged. Nothing needs to be re-issued.
  • They appear under the admin service account in Settings > Service Accounts.
  • Because they inherit the admin role, they retain full access.
note

The admin name is reserved for these migrated keys. You cannot create a new service account named admin.

We recommend using this as an opportunity to split broad admin keys into scoped, per-integration service accounts: create a dedicated member service account for each integration that does not need admin access, and migrate that integration to a key issued from the new account.

Personal API Keys​

Signadot does not offer per-user (personal) API keys today. API keys are issued only through service accounts. If you previously relied on a personal key, use a service-account key instead (see the admin account above).