API Keys

Stacktape API keys let you authenticate with Stacktape from the CLI or in CI/CD pipelines. Create keys with bounded expiration dates in the Stacktape Console, track when each key was last used, and revoke keys instantly when they are no longer needed or compromised. API keys are managed per-organization.

What API keys are for

API keys are useful for non-interactive automation where you do not want to rely on a browser-based login flow — CI/CD runners, headless servers, and automated scripts. API keys are created for the currently selected organization.

Use API keys when you need non-interactive authentication. For local development where a browser is available, stacktape login handles authentication for you, so you do not need to create and rotate a Console API key manually.

The keys on this page are personal: they act as you, with your role, projects and AWS accounts, and they stop working when you leave the organization. For CI, Owners and Admins create an organization key on the Members page instead. It belongs to the organization and keeps working when people leave.

Creating an API key

Open API keys from the profile menu in the Stacktape Console. Click New API key to open the creation form.

The creation form has two fields — only the API key name is required:

FieldDescription
API Key nameA human-readable label to identify this key (e.g. github-actions-prod, dev-laptop). Required.
ExpirationHow long the key remains valid. Manual API keys expire by default and cannot exceed 365 days.

After creation, copy the key immediately and store it in your CI/CD platform's secrets manager. Manual API keys are bearer secrets and are shown only once. Do not paste them into chat transcripts, issue trackers, source code, shell history, or plain-text config files.

Name keys after their purpose or location (ci-deploy-production, developer-alice-laptop) so you can identify and rotate them without guessing which integration depends on each key.

Key status and lifecycle

Each API key has one of three statuses:

StatusMeaning
ActiveThe key is valid. Metadata and revoke controls are available on the key card.
ExpiredThe key passed its expiration date. The Console marks a key as expired once its expiresAt time has passed.
RevokedThe key was manually revoked by a user.

The Console displays active keys separately from expired and revoked keys, which appear under an Expired & Revoked heading. Each key card shows:

  • Name — the label assigned at creation
  • Created — timestamp of creation
  • Last used — timestamp of the most recent use, or "never"
  • Expiration — remaining days until expiry, or the expired date
  • Revoked — timestamp of revocation (only shown for revoked keys)

The API keys page does not show a reactivation action for expired or revoked keys. Create a new key instead when you need to restore access for an integration point.

Revoking an API key

Click Revoke on any active key to open a confirmation dialog. The dialog warns that any CLI sessions or integrations using the key will stop working immediately. After confirming, the key is listed under the Expired & Revoked section. The Revoke button and partial key identifier are no longer shown on the key card.

Revoking a key takes effect immediately. Confirm that no running pipelines depend on the key before revoking, or create and configure a replacement key first.

Copying a key value

Manual key values are available only at creation time. If you lose a manual key value, create a replacement key, update the integration that uses it, verify the new key works, and revoke the old key.

Using an API key

API keys are intended for CLI and CI/CD authentication. After creating a key, copy it from the Console and store it securely. For CI/CD setup guidance, see Custom CI/CD or GitOps with Console.

Store the API key in your CI/CD platform's built-in secrets manager (GitHub Actions secrets, GitLab CI variables, etc.) rather than in plain text. This keeps the key out of command history, logs, and source control.

Permissions

Managing API keys requires the api-keys:manage-own permission. Users without this permission are redirected to /overview when they navigate to the API keys page. See Team and access control for details on managing user permissions.

A key can do what its owner can. A Developer's or Viewer's key reaches only the projects and AWS accounts chosen for them on the Members page; asking it for credentials in another AWS account fails with "Your access does not include the AWS account".

Best practices

These are general credential-management recommendations applicable to API keys:

  • Set a short enough expiration for CI/CD keys. The 90- or 180-day options balance security with maintenance overhead. Shorter windows (30-60 days) suit developer machines where stacktape login is an alternative.
  • One key per integration point. Sharing a single key across multiple pipelines makes revocation disruptive. Create separate keys for production deploys, staging deploys, and individual developer machines.
  • Rotate before expiration. The Console can show multiple active keys. Create the replacement key, update your CI/CD secret, verify authentication with the new key, then revoke the old key.
  • Monitor "Last used." Keys that show "never" or a date months in the past are candidates for cleanup.

API Keys FAQ

What expiration period should I choose?

Manual API keys expire by default and cannot exceed 365 days. As a general credential-management practice, shorter expirations reduce risk if a key is leaked. For developer machines, stacktape login handles authentication without requiring you to create and rotate a Console API key.

Can I reactivate an expired or revoked key?

The API keys page does not show a reactivation action for expired or revoked keys. Create a new key instead, update your integrations with the new value, and remove any references to the old key.

How do I rotate an API key without downtime?

The Console can show multiple active keys, so you can rotate without downtime. Create the new key first. Update your CI/CD secret or environment variable to the new value. Confirm authentication works with the new key. Then revoke the old key.

What happens when I revoke a key?

The Console confirmation dialog warns that any CLI sessions or integrations using the key will stop working immediately. After revoking, the key card moves to the Expired & Revoked section. The Revoke button and partial key identifier are no longer shown on the key card.

When should I use API keys vs interactive login?

Use stacktape login for local development — it opens a browser and authenticates you, so you do not need to create or rotate a Console API key manually. Use API keys for headless environments (CI/CD runners, automated scripts, shared build servers) where a browser is unavailable. Most teams use interactive login locally and API keys in their pipelines.

Are API keys scoped to a specific organization?

Yes. API keys are created in the context of the currently selected organization. When you switch organizations in the Console, you see only the keys belonging to that organization.