Skip to main content

Manage API tokens

Issue an organization API token, put it where your workflows can read it, and replace or revoke it later.

If you're setting up an organization for the first time, Connect your organization to the Bullfrog platform walks through this once as part of the whole flow. Come back here to manage tokens afterwards.

Before you begin​

  • Admin access to the organization in Bullfrog. Admins are the owners of the corresponding GitHub organization. See Roles and permissions.

What a token does​

A token identifies one organization. A job that passes one gets two things:

  • Its connection results are submitted to the control plane at the end of the run.
  • The egress policy that applies to it is fetched at the start of the run.

A job without a token does neither. It still filters egress using its own inputs and still writes a job summary, but it stays invisible to the platform and no policy can reach it.

Tokens have no expiry and no scopes. A token is valid for its whole organization until you delete it.

Create a token​

  1. In the left navigation, select Settings, then the API Tokens tab.
  2. Enter a name. It may contain letters, numbers, hyphens, and underscores, up to 200 characters. Name it after where it's used, such as github-actions or release-workflows.
  3. Select Create.

The token is displayed once, in a modal. Copy it before closing: Bullfrog stores only a hash, so it can't show you the value again. If you lose it, delete the token and create another.

The list afterwards shows each token's name, creation date, and last-used date.

Store a token as an Actions secret​

Create an organization secret so every repository can share one token:

  1. In GitHub, open your organization's Settings.
  2. Select Secrets and variables, then Actions.
  3. Select New organization secret, name it BULLFROG_API_KEY, and paste the token.
  4. Choose which repositories may read it.

For a single repository, create a repository secret under that repository's Settings → Secrets and variables → Actions instead.

warning

Don't write the token into a workflow file. Workflow files are readable by anyone who can read the repository, and a token that reaches a fork's logs is a token you have to replace.

Reference a token from the action​

- uses: bullfrogsec/bullfrog@7dee337d4575320b6d8cbe9a56d48d2fb765963a # v0.11.1
  with:
    egress-policy: audit
    api-token: ${{ secrets.BULLFROG_API_KEY }}

To confirm it works, run the workflow and open Workflow Runs. The run appears in the table, and the token's last-used date under Settings → API Tokens is no longer Never used.

Replace a token​

There's no rotation flow, so replace a token by overlapping the old one with the new:

  1. Create the new token.
  2. Update the GitHub secret to the new value.
  3. Wait for the workflows that use it to run, and confirm on Workflow Runs that results are still arriving.
  4. Delete the old token.

Delete a token​

Select the token in the list and select Delete. It stops working at once.

Jobs still passing that token keep building. They stop reporting results, stop receiving policy overrides, and fall back to whatever their workflow file configures.

See also​