API Keys

API keys are used to authenticate with the Signadot API and CLI. This page covers how to use and manage API keys in your organization.

Every API key belongs to a service account: a non-human principal that holds keys with its own role. Keys are created and managed under a service account rather than at the organization level, so automated access is attributable to a named account.

Who Can Create API Keys

Only users with the admin role can create and manage service accounts and their API keys. Members have read-only access, and viewers cannot see other users' API-key metadata. See Role-Based Access Control for details on roles and permissions.

Creating an API Key

API keys are issued under a service account. See Service Accounts > Issuing an API Key for the full flow:

1. Log in to the Signadot Dashboard.
2. Navigate to Settings > Service Accounts and open (or create) the service account the key should belong to.
3. On its Keys tab, click Create API Key.
4. Give the key a descriptive description.
5. Choose an expiration: 1 day, 1 month (the default), 90 days, a custom date, or no expiry. See Expiration.
6. Copy the key value immediately. It will not be shown again.

The key authenticates with the service account's role, and you authenticate with the key plus your organization name. Both values are needed.

note

Pre-existing organization-level keys are grouped under a reserved service account named admin and keep working unchanged. See Legacy Organization Keys. Per-user (personal) API keys are not offered; keys come only from service accounts.

caution

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

What API Keys Are Used For

CLI Authentication

The Signadot CLI uses API keys to authenticate against the Signadot API. There are several ways to provide credentials:

Auth command (recommended)

signadot auth login --with-api-key <api-key>

This stores credentials locally so they persist across CLI invocations. See signadot auth for more detail.

Environment variables

export SIGNADOT_ORG=<your-org>
export SIGNADOT_API_KEY=<your-api-key>

This is the most common approach in CI/CD pipelines and scripts.

CI/CD Pipelines

API keys are required to run the Signadot CLI in CI/CD environments such as GitHub Actions, GitLab CI, Jenkins, and Bitbucket Pipelines. Store the API key as a secret in your CI system and expose it as the SIGNADOT_API_KEY environment variable. See the CI/CD integration guides for platform-specific instructions.

Preview URL Access

When accessing preview URLs programmatically (e.g. via curl or in automated tests), include the API key in the signadot-api-key HTTP header:

curl -H 'signadot-api-key: <your-api-key>' \
  'https://my-endpoint--my-sandbox.preview.signadot.com'

Browser-based access to preview URLs does not require an API key if you are logged in to app.signadot.com.

Signadot API

The Signadot REST API uses the same API keys for authentication. Pass the key via the signadot-api-key header in your HTTP requests.

API Keys vs Browser Login

Signadot supports two authentication methods:

	API Key	Browser Login
Best for	CI/CD, scripts, programmatic access	Interactive CLI use, dashboard
Identity	A service account (a non-human principal)	Your user account
Created by	Admins only	Any user (self-service)
Expiration	Optional expiration set at creation, otherwise valid until revoked	Session-based

When to use API keys: CI/CD pipelines, automated scripts, programmatic preview URL access, and any non-interactive context.

When to use browser login: Day-to-day interactive CLI use, where signadot auth login opens a browser-based flow. This associates actions with your user identity, which is relevant for features like devboxes that use the authenticated user's email for identification.

Managing API Keys

Expiration

An API key can carry an optional expiration, chosen when the key is created. The Create API Key dialog offers 1 day, 1 month (the default), 90 days, a custom date, or no expiry. Once a key expires it is rejected at authentication time, and any CI pipeline or script using it will stop working, just as if the key had been revoked.

A key's expiration is shown in the Expires column on the service account's Keys tab, as either a date, Never, or a flagged Expired state. Plan to replace a key before it expires, following the rotation steps below.

Keys created without an expiration never expire. That includes every key created before expiration was introduced, and any key created through an older CLI, SDK, or direct API call, so existing automation is unaffected.

Revoking a Key

To revoke an API key, open its service account under Settings > Service Accounts, go to the Keys tab, and delete the key. Revocation is immediate. Any CI pipeline or script using that key will stop working.

Rotation

To rotate a key, whether it carries an expiration or not:

1. Create a new API key.
2. Update all systems that use the old key (CI secrets, local CLI config, scripts).
3. Revoke the old key.

Best Practices

• Use separate keys for separate purposes. Create distinct keys for each CI system, team, or environment so that revoking one key doesn't disrupt everything.
• Name keys descriptively. Use names like github-actions-prod or jenkins-staging so you can identify what each key is used for.
• Store keys securely. Use your CI platform's secrets management (GitHub Secrets, GitLab CI Variables, etc.). Never commit API keys to source control.
• Set an expiration. Bounding a key's lifetime at creation limits the impact of a key that leaks or is forgotten. Where a key must not expire, rotate it periodically instead.
• Revoke unused keys. Regularly audit your API keys and remove any that are no longer in use.

Data Security

Signadot does not store API keys in plaintext. Only hashed values and masked display values are retained. All API key data is stored in an encrypted database and is only accessible over TLS. See Data & Integrations for more on Signadot's security practices.