# Evaluation credentials

Create, store, rotate, and revoke environment-bound server and browser keys.

Evaluation credentials belong to one project environment. Their binding is fixed by the key record;
callers cannot choose another project or environment at request time.

Raw secrets are returned only at creation. Later lists show metadata and a prefix. If the receipt is
lost, create a replacement because FeatureGate cannot recover the original value.

## Credential families

| Credential         | Scope              | Exposure    | Use                                        |
| ------------------ | ------------------ | ----------- | ------------------------------------------ |
| Server runtime key | `runtime:evaluate` | Secret      | Hosted server evaluation                   |
| Server runtime key | `runtime:snapshot` | Secret      | Snapshot, polling, and invalidation        |
| Browser client key | `client:evaluate`  | Publishable | Exposed browser flags from allowed origins |
| Management key     | Management scopes  | Secret      | Preview control-plane automation           |

Never use a management key for runtime evaluation. Never use a server runtime key in a browser or
mobile bundle.

## Create a server runtime key

Open the project **Environments** page and select the intended environment. Create a key with only the
scopes required by the integration.

Use `runtime:snapshot` for the Node.js SDK. Use `runtime:evaluate` for direct HTTP evaluation. A server
integration that needs both can receive both scopes, but least privilege is easier to rotate and audit.

Snapshot access exposes every active typed flag, server-only value, and ordered targeting rule in the
environment. Treat that key as a high-value application secret.

Store server keys in a deployment secret manager. Do not commit them, place them in frontend build
variables, print them, or attach them to error reports.

## Create a browser client key

Client keys use only `client:evaluate`. Add every exact origin that may call FeatureGate, including
scheme and port where applicable.

`https://app.example.com` and `https://admin.example.com` are different origins. A local development
origin such as `http://localhost:5173` must be listed explicitly when required.

Requests without `Origin`, or from an origin outside the allowlist, are rejected. A valid key can
evaluate only configurations with client exposure enabled.

The key is publishable, not unrestricted. Anyone can inspect it and call from an allowed browser
origin. Expose only values safe for users to observe.

## One key per operational owner

Use separate keys for independently deployed callers or rotation owners. A shared key makes it harder
to identify usage, revoke one compromised integration, and coordinate deployment.

Name keys after the caller and purpose, such as `checkout-api snapshot` or `storefront browser`.
Do not put secrets, emails, or incident data in the display name.

## Rotate without interruption

1. Create a replacement in the same environment with the required scopes.
2. Capture the one-time secret directly into the secret-management workflow.
3. Deploy the replacement while the old key remains active.
4. Verify successful evaluation or snapshot refresh from the intended caller.
5. Revoke the old key.
6. Confirm the revocation event in activity.

Never revoke first unless responding to suspected compromise. If compromise is likely, revoke
immediately and accept that callers may use defaults until the replacement deploys.

Revocation stops future requests. It cannot erase snapshots already held in running processes. Those
processes may continue evaluating their last in-memory state until refresh, restart, or shutdown.

## Failure cases

- `401` usually means the key is malformed, unknown, or revoked.
- `403` can mean missing scope, wrong credential family, disallowed origin, hidden flag, or offboarding.
- A lost one-time secret must be replaced, not recovered.
- A key for staging cannot evaluate production, regardless of request content.
- A browser key cannot fetch snapshots or reveal server-only configuration.

Related pages: [Rotate runtime keys through automation](/docs/automation/rotate-runtime-keys),
[Errors and fallbacks](/docs/evaluate/errors-and-fallbacks), and
[Activity and audit history](/docs/operate/activity-and-audit).