API keys

This page is for the owner or admin who hands out API keys. By the end you’ll have created a key for a script or service, and you’ll know how to see which keys are in use and how to revoke one.

An API key lets something other than a person, such as a CI job or an internal tool, read or change tickets through By Dawn’s board API. A key belongs to your organization, not to the person who made it, so it keeps working when they leave. What a key can and can’t do, and how a developer uses it, is on Authentication in the Developers space.

Keys live in Settings›, then Organization›, then Security, on the API keys card. Owners and admins can see, create and revoke them. Members don’t see the Security section at all.

Create a key

1. Under API keys, type a Name you’ll recognise later, such as CI deploy or the name of the tool.

2. Pick its Access:

   • Board — read only: “Reads tickets on the board API.”
   • Board — read & write: “Reads, creates and updates tickets on the board API.”
   • Tests — submit results: “Sends test results from CI (saw-agent tests submit) — no board access.”
   • Tests — read cases & runs: “Reads the test case library, its runs and results — no board access.”
   • Tests — read & write cases & runs: “Also creates and edits test cases, folders and manual runs, and sends CI results — no board access.”
   • Customers only: “Works with customers alone — no board access. Pick its Customers access.”

   Start with read only, and make a read & write key only for something that needs to change tickets. A key for a CI job that sends test results needs only Tests — submit results, which can’t read or change tickets at all. Importing test cases needs Tests — read & write cases & runs.

3. Pick its Customers access, for a key that works with your organization’s customers:

   • None: “No access to customers.” It’s the default.
   • Read: “Reads customers and their requests.”
   • Read & write: “Also creates and updates customers. Adding a request to a ticket needs board access too.”

   A key that syncs customers from your CRM needs Read & write here. If it also records which tickets they asked for, give it a Board access as well, because a request is added to a ticket. Customers only keys can’t pick None, and a Realtime publish (legacy) key can’t have customer access.

4. Pick when it Expires: 30 days, 90 days, 365 days or Never. It starts at 90 days.

5. Choose Create key.

6. By Dawn shows the key once: “Copy this key now — it’s shown only once.” Choose Copy, store it where the script or service reads its secrets, then choose Done.

The key starts with saw_live_ and the first part of it, up to the dot, is its prefix. By Dawn only keeps a fingerprint of the rest, so it can’t show you the key again. If you lose it, create a new one and revoke the old one.

Realtime publish (legacy)

Access also offers Realtime publish (legacy): “Publishes realtime events only — no board access.” It’s for older integrations. Pick one of the other options for anything new.

See which keys are in use

Each key in the list shows its name, its prefix and when it was last used, such as used today or never used, with badges for its access (Read & write, Read, Tests: read & write, Tests: read, Tests or Legacy), its customer access when it has some (Customers: read & write or Customers: read) and its expiry (Expires and a date, No expiry or Expired). The newest keys come first.

The prefix is how you match a key to the place it’s used, because that’s the part people can see in a config file without the secret. An expired key stays in the list until you revoke it, so you can tell what stopped working and why.

Revoke a key

Choose Revoke next to the key, then Revoke key. By Dawn warns you first: anything calling with that key “loses access within seconds. A revoked key can’t be restored — callers that still need access will need a new key.”

To replace a key without a gap, create the new one, switch the script or service over to it, and only then revoke the old one.

Tip

When someone leaves, revoke any key they had a copy of, and replace the ones still in use. Removing a person from the organization doesn’t revoke keys, because the keys belong to the organization, and the list doesn’t show who made each one, so name keys after the tool, not the person.

GitHub Actions trusts

A GitHub Actions trust lets workflows in one of your GitHub repositories send test results to a By Dawn project with no key at all. GitHub signs each job with a short-lived token that names its repository, and By Dawn accepts the token when a trust names that repository. Nothing secret is stored in the repository, so there’s nothing to rotate. Sign in with GitHub’s OIDC token shows the workflow side.

Trusts are on the GitHub Actions card, under API keys. A trust can only name a repository owned by the GitHub account your organization has connected, so connect GitHub first. The card says “Connect GitHub first” until you do.

1. Type a Name you’ll recognise later, such as Web CI.

2. Type the Repository’s name. The owner, your connected GitHub account, is filled in for you. You can also paste the repository’s GitHub address.

3. Pick the Project whose test results the repository sends.

4. Optionally narrow it:

   • Branch: only workflows running on this branch, such as main, may send results. Blank trusts every branch.
   • Environment: only jobs that run in this GitHub deployment environment may. A protected environment with required reviewers makes this the strictest choice.

5. Pick when it Expires. A trust has no secret to leak, so it defaults to never.

6. Choose Trust repository. By Dawn shows the workflow step to add, with Copy.

A trust can only send test results, to its one project. It can’t read anything, and it can’t send results to your other projects. The list shows when each trust was last used. To stop one, choose Revoke, then Revoke trust. Workflows using it are refused within seconds. Disconnecting GitHub stops every trust too.

If a repository is renamed on GitHub, or deleted and made again under the same name, the trust no longer matches it, so add a new one.

Keys and the sign-in policy

An API key has its own way of signing in, separate from the methods people use. Turning methods off in Sign-in methods doesn’t affect keys.

FAQ

Is there a limit on how many keys we can have?

No. It’s still worth one key per script or service, so you can revoke one without breaking the others, and the used date tells you which are still alive.

Who shows as the author of a ticket a key creates?

The key does, not a person. Authentication lists what else is different about a key.

Where to go next

• Authentication: what a key may do, and how code exchanges it for a token.
• Security: the rest of the Security section.