Skip to content

article

Managing API Keys

How to create scoped API keys, copy the secret once, and rotate, pause, revoke, or delete keys in the StretchDev API console.

Overview

StretchDev's API console lets you issue scoped API keys so external systems — CI pipelines, scripts, dashboards — can talk to StretchDev programmatically. Each key has a name, a set of scopes that limit what it can do, a status, and an optional expiry. Keys are scoped to your organization automatically. This article covers creating, viewing, rotating, and retiring keys.

Create an API key

1. Open the API console and go to API keys.
2. Click New key.
3. Fill in:
- Name (required) — a label like CI pipeline or Nightly report script.
- Scopes — what the key may do. Defaults are projects:read, repos:read, and webhooks:read. Grant only the scopes the integration actually needs.
- Expiry (optional) — an expiration date; leave empty for a non-expiring key.
4. Click Create. StretchDev shows the full secret once — it looks like sgdev_xxxxxxxxxxxxxxxxxxxx. Copy it now and store it in your secrets manager.

Important: The full secret is displayed only at creation. StretchDev stores just a hashed form and a short prefix (for example sgdev_Ab3dEf...) for identification. If you lose the secret, you can't recover it — rotate the key to get a new one.

View and identify keys

The API keys list shows each key's name, prefix, scopes, status (active, paused, or revoked), expiry, last-used time, and who created it. Use the prefix to match a key to the secret you stored, without ever exposing the full value.

Rotate, pause, revoke, delete

  • Rotate — issues a brand-new secret for the same key and re-activates it. Use this on a schedule, or immediately if a secret may be exposed. The old secret stops working; update your integration with the new one shown at rotation.
  • Pause — set the key's status to paused to temporarily block it without deleting it. Reactivate by setting it back to active.
  • Revoke — set the status to revoked to permanently disable it while keeping the record for audit.
  • Delete — remove the key entirely. Use when an integration is fully retired.

You can also rename a key, change its scopes, or update its expiry at any time.

Example

You're wiring StretchDev into your CI. You create a key named CI – read projects with scopes projects:read and repos:read and a 90-day expiry. You copy the sgdev_… secret into your CI secret store. Ninety days later, ahead of expiry, you rotate the key, update the CI secret, and confirm the pipeline still runs — no downtime, and the old secret is dead.

Tips

  • Least privilege: grant only the scopes an integration needs; a read-only reporting job never needs write scopes.
  • One key per integration so you can rotate or revoke one without breaking the others, and so request logs clearly attribute traffic.
  • Set an expiry on keys for third parties or short-lived jobs.
  • Rotate on a schedule and immediately if a secret might have leaked.
  • Store secrets in a secrets manager, never in source control.

Troubleshooting

  • "An API key name is required." Provide a name before creating.
  • "API key not found." The key ID doesn't match a key in your organization — confirm the workspace and that it wasn't deleted.
  • My integration suddenly gets rejected. The key may be paused, revoked, or past its expiry — check its status, or rotate to a fresh secret.
  • I lost the secret. It can't be recovered; rotate the key and update your integration with the new value.

Was this helpful?

Help us improve this article

Use these controls to share whether this answer solved the issue. Feedback helps prioritize updates to StretchSuite Support.