---
title: "Service Keys"
description: "Long-lived API keys that belong to your organization, not to a user — purpose-built for CI/CD scanning."
url: https://docs.stackhawk.com/platform/service-keys/
---

# Service Keys

Service Keys are long-lived API keys that belong to your organization rather than to a specific user. Use them when you need StackHawk credentials for automation — today, that means running scans from CI/CD.

Unlike personal API keys (created from **Settings → API Keys**), a service key is owned by the organization itself, so its lifecycle is managed at the org level and independent of any individual user account.

![Service Keys page with a table of existing keys and a Create Service Key button](https://docs.stackhawk.com/images/platform/service-keys/service-keys-list.png)

## When to Use a Service Key

Service keys are a powerful but deliberately narrow feature. Today they ship with a single role — **Scan Only** — which limits them to running and uploading scans. Reach for a service key when the caller is a CI/CD pipeline; stick with a personal API key for anything else.

| Use Case | Use a Service Key? |
| - | - |
| Scanning from a CI/CD pipeline (GitHub Actions, GitLab CI, Jenkins, etc.) | **Yes** — the key belongs to the organization, not to whoever set up CI |
| A developer running ad-hoc scans from their laptop | No — use a **personal API key** under **Settings → API Keys** |
| Reading findings, managing applications, or anything besides running scans | No — the Scan Only role cannot perform these actions. Use a personal API key owned by a user with the appropriate role |

## Prerequisites

- Your organization must have the **Service Keys** feature enabled. [Contact StackHawk](mailto:support@stackhawk.com) if you don’t see **Service Keys** in **Settings**.

- Managing service keys is permission-gated:

  - Viewing the **Service Keys** page requires the **Read Service Account** permission.
  - Creating a service key requires the **Write Service Account** permission.
  - Deleting a service key requires the **Delete Service Account** permission.

  The UI hides controls you don’t have permission to use — the sidebar entry is hidden without Read, the **Create Service Key** button is hidden without Write, and the row-level trash icon is hidden without Delete.

## Creating a Service Key

Access Service Keys from **Settings → Service Keys** in the platform.

1. Click **Create Service Key**.
2. Enter a descriptive **Name** (e.g., `github-actions-prod`, `nightly-scan-runner`). The name also shows in the audit log so use something that identifies the automation.
3. Choose a **Role**. Today, only **Scan Only** is available — it grants the minimum permissions needed to run and upload scans.
4. Click **Create**.

![Create Service Key modal with Name and Role inputs](https://docs.stackhawk.com/images/platform/service-keys/create-service-key.png)

StackHawk shows the new key **once** in a banner at the top of the Service Keys page.

> **Warning:** **Save the key immediately.** StackHawk stores only a hash, so there is no way to retrieve the full value later. If you lose it, delete the service key and create a new one.

![One-time secret reveal banner with the new key value and a copy icon](https://docs.stackhawk.com/images/platform/service-keys/reveal-secret.png)

Click the copy icon to put the key on your clipboard, then paste it into your secret manager of choice (GitHub Actions secrets, AWS Secrets Manager, Vault, etc.).

## Using a Service Key

A service key authenticates the same way as a personal API key — set the `HAWK_API_KEY` environment variable and run your scan. There is no special CLI mode for service keys.

### In a CI/CD pipeline

Store the key as a secret in your CI provider and expose it to the scan step:

```yaml
# GitHub Actions example
- name: Run HawkScan
  uses: stackhawk/hawkscan-action@v3
  env:
    HAWK_API_KEY: ${{ secrets.STACKHAWK_SERVICE_KEY }}
```

### From a local script

```bash
export HAWK_API_KEY="sh_your_service_key_value"
hawk scan
```

See [HawkScan — Running HawkScan](https://docs.stackhawk.com/hawkscan/running-hawkscan/) for the full scan invocation reference.

## Roles

Today, **Scan Only** is the only role a service key can have. A Scan Only key is purpose-built for CI/CD scanning and deliberately narrow.

**A Scan Only service key can:**

- Read organization, team, and application metadata needed to run the scan (including across teams, so a CI key can reach any application it is given)
- Read scan policies and scan configuration
- Read and update the application’s scan configuration during the scan
- Create scans, upload scan results, and read scan data

**A Scan Only service key cannot:**

- Triage findings or modify alert rules
- Manage users, teams, or integrations
- Modify organization-wide settings or billing
- Read the audit log
- Create, modify, or delete other service keys

StackHawk may add additional service key roles over time; new roles will appear in the **Role** dropdown automatically.

## Security Recommendations

- **One key per pipeline or environment.** Prefer many narrowly-scoped keys over a single shared key so you can delete one without disrupting others.
- **Give keys descriptive names.** The name shows in the audit log against every scan the key runs. `github-actions-prod-checkout-service` is more useful during an investigation than `ci-key`.
- **Store keys only in your secret manager.** Never commit a key to source control or paste it into chat. StackHawk cannot show you the secret a second time.
- **Rotate periodically.** There’s no forced rotation window — establish your own cadence appropriate to your environment’s sensitivity.
- **Delete unused keys.** If you retire a pipeline, delete its service key rather than leaving it active.

## Deleting a Service Key

1. On the **Service Keys** page, click the trash icon on the row you want to remove.
2. Confirm in the dialog.

Deletion is immediate and cannot be undone. Any automation using the deleted key will start receiving `401 Unauthorized` on its next request, so drain or update dependent pipelines first.

![Delete Service Key confirmation modal](https://docs.stackhawk.com/images/platform/service-keys/delete-service-key.png)

## Audit Log

Every service key action is recorded in **Settings → Audit Log**:

- **Service Key Created** — includes the key name and role at creation
- **Service Key Deleted** — includes the key name and role at deletion

Actions performed *using* a service key (starting scans, uploading results) appear in the audit log under the key’s name with a `(Service Account)` suffix — for example `github-actions-prod (Service Account)` — making it easy to trace which automation ran a scan.

## Troubleshooting

### My automation started getting `401 Unauthorized` out of nowhere

Check, in order:

1. **The key still exists.** Open **Settings → Service Keys** and confirm the row is still there. Service keys are deleted immediately — there is no grace period. A teammate may have deleted it.
2. **`HAWK_API_KEY` is set and is the full key.** The secret starts with `sh_`. If your CI provider truncated or masked the value, rotate by creating a new key and replacing the secret.
3. **The feature flag is still on.** If the **Service Keys** feature was disabled on your organization, the key becomes unusable.

### I created a key but can’t see it in the list

- **Hard-reload the browser.** The list is cached in-page; a soft reload may not refetch.
- **Check your permissions.** You need the **Read Service Account** permission to view the list. Someone with Admin or Owner access should confirm your role’s permissions.

### The Create button is missing

You lack the **Write Service Account** permission. Ask an Admin or Owner to create the key for you, or to grant you the permission if that’s appropriate for your role.

### The trash icon is missing on a row

You lack the **Delete Service Account** permission. Same remedy as above.

## Frequently Asked Questions

### How is a Service Key different from a personal API Key?

A personal API key is issued to and owned by a specific user. A service key is owned by your organization directly — its lifecycle is managed at the org level rather than tied to any individual user account.

### Can I rotate a Service Key in place?

Not today. To rotate, create a new service key, switch your automation to the new service API key, then delete the old one.

### How many Service Keys can I have?

There is no hard limit. Create one per independent automation so you can delete individual keys without affecting others.

### Does deleting a Service Key revoke its API key immediately?

Yes. Deletion is atomic — the key and all of its authentication credentials are removed in a single step. Any in-flight requests will complete; the next request using the deleted key returns `401 Unauthorized`.
