Organization Secrets

Organization secrets are stored values that belong to your organization rather than to one user account. Any scan run under the organization can resolve them, so a shared credential — a staging database password, a service token your whole team scans with — is stored once instead of once per engineer.

They interpolate into your HawkScan configuration exactly like user secrets and are redacted in scan logs the same way. The difference is who can use them: a user secret resolves only for scans that user runs, while an organization secret resolves for everyone.

Prerequisites

• Your organization must have the Organization Secrets feature enabled. Contact StackHawk if you don’t see the Organization Secrets tab under Settings → Secrets.
• Access is permission-gated, and the permissions are not granted to every role. See Permissions.

Creating an Organization Secret

Navigate to Settings → Secrets and select the Organization Secrets tab:

1. Click Add New
2. Enter a name using environment variable convention (e.g., SHARED_DB_PASSWORD)
3. Enter the secret value
4. Save the row

Names may contain uppercase letters, digits, underscores and hyphens, up to 64 characters. Pick a name you would not expect to collide with an ordinary environment variable on a scanner host, so it is obvious where a value came from.

Using an Organization Secret

Reference it in stackhawk.yml the same way you would any environment variable:

app:
  authentication:
    usernamePassword:
      scanPassword: ${SHARED_DB_PASSWORD}

HawkScan resolves the reference at config-parse time, before the scan starts.

Resolution order

For each unresolved ${VAR}, HawkScan takes the first match:

1. A local environment variable, or one supplied with --env/--env-file
2. A user secret belonging to the authenticated identity
3. An organization secret belonging to the organization the scan runs under
4. Otherwise the value resolves to empty and the scan continues

A user secret of the same name therefore overrides the organization’s, which lets an individual point at their own credential without changing anything shared. The precedence is enforced by the scanner, not by which store you happen to write to.

Which organization a scan resolves against

The one that owns the application under scan. HawkScan reads app.applicationId from your config and asks the platform which organization it belongs to, so nothing extra has to be configured and there is no environment variable to set — in CI or anywhere else.

This is why it works the same whether the scan runs from your laptop, from your own CI, or on StackHawk’s hosted scanner, and why it is unambiguous even if you belong to several organizations: the application decides, not the account running the scan.

It also means the answer is bounded by access you already have. A scan must be authorized against its application to upload results at all, and the same check applies here — you cannot read one organization’s secrets by pointing a scan at another organization’s application.

The only case with no answer is a config whose applicationId is itself an unresolved ${VAR}. There is no application to ask about, so no organization secrets are resolved and those references come back empty.

Permissions

Action	Permission
See the Organization Secrets tab, and resolve secrets during a scan	Read Organization Secret
Create or update a secret	Write Organization Secret
Delete a secret	Delete Organization Secret

Role	Read	Write	Delete
Owner	Yes	Yes	Yes
Admin	Yes	Yes	Yes
Team Admin	Yes	Yes	—
Scan Only service key	Yes	—	—
Member	—	—	—
View Only	—	—	—

The list view shows a secret’s name and metadata but never its value. The value is only ever returned by an explicit resolve, which requires Read Organization Secret.

Minimum HawkScan version

Organization secrets require HawkScan 6.5.0 or newer.

An older scanner does not know the organization routes exist. It will not error — it substitutes an empty string for the unresolved reference and the scan proceeds. So a pipeline on an old scanner authenticates with a blank credential and typically fails somewhere further along, or silently scans far less of your application than you expect.

Check what a runner is using:

hawk version

If you have pipelines on mixed versions, keep a user secret or a plain environment variable in place for the older ones until they are upgraded. The user secret takes precedence, so the two can coexist during a rollout.

Secrets in scan tags are not secret

A secret interpolated into a scan tag is uploaded to the platform as part of the scan record and stored in plaintext:

tags:
  - name: DB_PASSWORD
    value: ${SHARED_DB_PASSWORD}   # don't — this is stored and displayed in clear text

Tags are metadata, not secret storage. Interpolate secrets into authentication fields, headers and request bodies — never into tags.

Related

• Secrets Management — per-user secrets
• Service Keys — the organization-owned credential to scan with in CI
• Roles — what each role can do