API keys

An API key lets something outside GitHub Actions talk to Midstream as your workspace. If your tests run on GitHub Actions, you do not need one.

When you need one

On GitHub Actions, the SDK picks up the GITHUB_TOKEN that Actions provides to every job and authenticates with that. Nothing to create, nothing to store.

You need an API key when:

• Your tests run somewhere else — CircleCI, GitLab CI, Buildkite, Jenkins, a build box under a desk.
• You are calling the Midstream API from your own script or service.

Set it as MIDSTREAM_API_KEY in the environment. The SDK finds it there.

MIDSTREAM_API_KEY=mst_your_key_here npx playwright test

If both are set, the API key wins. The SDK checks MIDSTREAM_API_KEY before GITHUB_TOKEN, so a key left in a GitHub Actions environment quietly takes over from the built-in token. Captures still register: the SDK sends GITHUB_REPOSITORY whichever credential it uses, so the project is still worked out from the repository.

Creating a key

Workspace settings → API keys → New key. Give it a name describing where it will run — "CircleCI", "release script" — because the name is the only thing you will have to recognize it by later.

The full key is shown once, on the screen that creates it. Copy it then. We store only a hash of it, so there is no page, no support request, and no database query that can show it to you again. Lose it and you create a new one.

A key looks like this:

mst_kR8vN2xQ7mYpL4wZ3jH6bT9cF1sD5gA0eU8iO2nV

Afterwards the list shows it as mst_...O2nV — the prefix and the last four characters. That is enough to tell two keys apart when you are deciding which one to revoke, and not enough to use.

What a key can do

A key authenticates as the workspace, not as the person who created it. It can register captures for any project in that workspace. The list records who created it and when, but the key keeps working after that person leaves.

A key is not scoped to a single project. Midstream normally works out which project a capture belongs to from the repository the test ran against; when it cannot, set MIDSTREAM_PROJECT to the project's slug. See "Running Midstream in CI" for the details.

Last used

The list shows a Last used timestamp for each key, updated whenever the key authenticates a request. It is written in the background, so it can lag a moment behind a request that is still in flight.

Use it for the two questions it answers well: is this key still in use by something I have forgotten about? and did my new CI configuration actually reach us? If you set up a key an hour ago and it has never been used, the problem is upstream of Midstream.

Revoking a key

Revoking is immediate and permanent. There is no un-revoke. The key disappears from the list and any request carrying it is rejected from that moment on.

Know what revoking looks like from the outside. The scene call in your tests is built never to fail a test — if it cannot reach Midstream, it warns in the log and the test carries on green. So revoking a key that CI is still using does not turn a build red. It makes new captures stop appearing, and nobody notices for a day. If captures have gone quiet, an accidentally revoked key is the first thing to check.

To rotate without a gap:

1. Create the new key.
2. Update the secret in your CI system and run one build with it.
3. Confirm the new key's Last used timestamp has moved.
4. Revoke the old one.

Looking after a key

• Treat it like a password. Anyone holding it can write captures into your workspace and read your projects.
• Store it in your CI system's secret store, never in the repository, never in midstream.json.
• Issue one key per system that needs one. Shared keys cannot be revoked without taking down everything that shares them.
• Creating and revoking a key are both written to the workspace audit log, with the key's name and who did it. See Members and roles.