# API keys

> Create, look after and revoke your By Dawn organization's API keys, which let scripts and services use the board API.

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](https://docs.bydawn.com/developers/authentication/) in the Developers space.

Keys live in **Settings › Organization › 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](https://docs.bydawn.com/developers/tests-submit/) needs only **Tests — submit results**, which can't read
   or change tickets at all. [Importing test cases](https://docs.bydawn.com/tests-migrate/) needs **Tests — read & write cases & runs**.

3. Pick its **Customers** access, for a key that works with your organization's [customers](https://docs.bydawn.com/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](https://docs.bydawn.com/developers/tests-submit/#sign-in-with-githubs-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](https://docs.bydawn.com/repos/), 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](https://docs.bydawn.com/security/#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](https://docs.bydawn.com/developers/authentication/#what-a-key-cant-do) lists what else
is different about a key.

## Where to go next

- [Authentication](https://docs.bydawn.com/developers/authentication/): what a key may do, and how code exchanges it for a token.
- [Security](https://docs.bydawn.com/security/): the rest of the Security section.

Source: https://docs.bydawn.com/api-keys/