Skip to main content

API Keys

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

Who Can Create API Keys​

Only users with the admin role can create and manage API keys. Members have read-only access. See Role-Based Access Control for details on roles and permissions.

Creating an API Key​

  1. Log in to the Signadot Dashboard.
  2. Navigate to Settings > API Keys (direct link).
  3. Click Create API Key.
  4. Give the key a descriptive name (e.g. ci-github-actions, dev-alice).
  5. Copy the key value immediately --- it will not be shown again.

When you create an API key, the dashboard displays both the API key and your organization name. Both values are needed for authentication.

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 KeyBrowser Login
Best forCI/CD, scripts, programmatic accessInteractive CLI use, dashboard
IdentityNot tied to a specific userTied to your user account
Created byAdmins onlyAny user (self-service)
ExpirationDoes not expire (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​

Revoking a Key​

To revoke an API key, go to Settings > API Keys in the dashboard and delete it. Revocation is immediate --- any CI pipeline or script using that key will stop working.

Rotation​

Signadot API keys do not expire automatically. To rotate a key:

  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.
  • Rotate keys periodically. Even though keys don't expire, periodic rotation limits the impact of a compromised key.
  • 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.