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. The Your API key is ready dialog shows the key. Copy it, then tick I've saved my key securely and will keep it private. to enable Done.

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.

Keep it private

Don't put a key in public repositories or public-facing interfaces, such as a shared dashboard panel, a notebook you publish or a page served to browsers. Anyone who finds it can use it until it expires or is revoked. If a key is exposed, revoke it and create a new one.

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.3.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. Earlier versions cannot run metrics sync, metrics validate, metrics debug or dashboards create with a key, so update the CLI before you use one:

Bash
export SIGNALFLAG_API_KEY=<your key>
signalflag projects list

You can also save the key as api-key: <your key> in ~/.signalflag/signalflag.yaml.

Use a key or older credentials, not both

The CLI stops with ambiguous authentication arguments provided if it finds an API key and also a client ID and secret, or a username and password. It checks flags, environment variables (including the older RESIM_ names) and signalflag.yaml. When you switch to a key, remove the old credentials from all of them.

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 in the list so you can see what they were used for. The tab shows active keys by default. To see the others, change the Status filter above the list to Expired keys, Revoked keys or All keys.