Skip to content

API Keys

An API key lets a script, a CI pipeline, an external tool or an agent use SignalFlag without signing in as a person. Each key belongs to your organization, so it keeps working when people join or leave, and you can give it only the access it needs.

Org admins create and revoke keys in the web app. Everyone in the organization can see the list of keys.

Choose the access

Every key has one of two access levels:

  • Read only can see everything in your organization and run queries, but cannot change anything. Use it for dashboards, reports and exporting data.
  • Read & write can do what a member of your organization can, such as creating projects, registering builds and launching tests. Use it for CI pipelines.

Pick read only unless the job needs to change something. A key cannot create or revoke other keys: that always takes an org admin signed in as themselves.

Create a key

In the web app:

  1. Open Org Settings and go to the API Keys tab.
  2. Select Create API Key.
  3. Give the key a name that says what uses it, for example nightly-ci or grafana-dashboards. Names must be unique among your organization's active keys.
  4. Choose the access and when the key expires: 30, 90 or 365 days, or never. New keys are read & write and expire after 90 days unless you choose otherwise.
  5. Select Create key, then copy the key.

The key is shown only once. SignalFlag stores a fingerprint of it, not the key itself, so if you lose it you have to create a new one. Store it in your CI service's secrets or your tool's credential store, never in source code.

Keys start with sfk_. In the list of keys, the first characters of each key are shown so you can tell them apart.

Use a key

Send the key as a bearer token. There is no token to exchange first.

With the API:

Bash
curl -s https://api.resim.ai/v1/projects \
  -H "Authorization: Bearer $SIGNALFLAG_API_KEY"

With the CLI (v1.2.0 or later), set the key as SIGNALFLAG_API_KEY or pass it with --api-key. The CLI sends it with every request and never saves it to disk:

Bash
export SIGNALFLAG_API_KEY=<your key>
signalflag projects list

Keys are created and revoked in the web app, not with the CLI.

With our GitHub Action (v1.9.0 or later), pass a read & write key as the api_key input:

YAML
- uses: resim-ai/action@v1.9.0
  with:
    api_key: ${{ secrets.SIGNALFLAG_API_KEY }}

With an agent, add the key as a header when you connect to the MCP server. This suits agents that run unattended, such as a step in a CI pipeline. Using Claude Code as the example:

Bash
claude mcp add --transport http signalflag https://bff.resim.ai/mcp \
  --header "Authorization: Bearer $SIGNALFLAG_API_KEY"

To query your data from Grafana, a notebook or a BI tool, see Query from External Tools.

Manage keys with an agent

An agent connected to the MCP server as you can list your organization's keys and propose new ones or revocations, for example while it sets up a CI pipeline for you. It never creates or revokes a key on its own: an org admin approves each proposal in the web app, in the same dialog as creating or revoking a key by hand.

When an admin approves a new key, the key is shown to that admin only, never to the agent. Copy it into your CI service's secrets or your tool's credential store yourself.

See Managing API keys for the tools involved.

Expiry and reminders

When a key is about to expire, every org admin gets an email 30 days, 7 days and one day before, naming the key and when it expires. Reminders that would arrive before the key was created are skipped, so a 30-day key only gets the last two.

To replace a key, create a new one, switch whatever uses the old key over to it, then revoke the old one. Once a key expires it stops working and cannot be renewed.

Revoke a key

Revoke a key as soon as it is no longer needed, or if it may have been exposed.

In the web app, select Revoke on the key in the API Keys tab, and type the key's name to confirm.

A revoked key stops working everywhere straight away, and revoking cannot be undone. Revoked and expired keys stay under Inactive keys so you can see what they were used for.