> ## Documentation Index
> Fetch the complete documentation index at: https://evsim.synergyboat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an API key

> Create, store, rotate and revoke the evrt_ API key that authenticates every request to the EV Roaming Tester public API from your scripts and CI.

Everything the public API does authenticates with one credential: an API key beginning
with `evrt_`. Keys are created in the app, never through the API.

## Prerequisites

* A **paid plan**. The free tier is for interactive evaluation in the browser; it cannot
  create API keys.
* A signed-in account with access to **Settings**.

## Create the key

1. Sign in at [evsim.synergyboat.com](https://evsim.synergyboat.com).
2. Open **Settings**, then **Security**.
3. Choose **Create key** and give it a name that says where it will be used, such as
   `github-actions-roaming-ci`. The name is how you will recognise it at revocation time.
4. Copy the key.

<Warning>
  The plaintext key is shown **once**, at creation. It is not retrievable afterwards:
  the app lists only the key's name, prefix and metadata. If you lose it, revoke it and
  create a new one.
</Warning>

## Store it like a secret, because it is one

Put the key straight into a secret manager (GitHub Actions secrets, GitLab CI variables,
Vault, AWS Secrets Manager) and expose it to jobs as an environment variable:

```bash theme={null}
export EVRT_KEY="(paste from your secret manager, not from a file in the repo)"
```

Then reference only the variable in scripts:

```bash theme={null}
curl -fsS "https://evsim.synergyboat.com/api/v1/usage" \
  -H "Authorization: Bearer $EVRT_KEY"
```

Rules that prevent the common leaks:

* Never commit a key, paste it into a ticket, or hardcode it in a script.
* Never `echo` the key or pass it as a command-line argument that lands in shell history
  or CI logs. Read it from the environment.
* Give each pipeline its own key, so revoking one does not break the others.

## Rotate and revoke

Rotation is create-then-revoke:

1. Create a new key in **Settings**, then **Security**.
2. Update the secret in your CI store.
3. Revoke the old key from the same page.

Revocation is immediate: requests with a revoked key start returning `401`. Revoke a key
the moment you suspect it leaked; creating its replacement takes seconds.

Your plan caps the number of active keys. Read the cap and your current count from
[`GET /api/v1/usage`](/docs/api#limits-and-usage) rather than assuming a number.

## There is no key-management API, deliberately

Creating, listing and revoking keys requires your signed-in browser identity. An
`evrt_` key cannot mint another key, list your keys, or revoke one. This keeps a leaked
CI key from quietly granting itself successors.

## Next

Run your [first conformance run from the command line](/docs/guide/quickstart).