# API keys

Create, rotate, and revoke server credentials in the business dashboard.

Manage keys at [Business Keys](/dashboard/business/keys). Choose the key type
that matches the operation. The API and CLI `--json` output call the type the
`scope` field, with the value shown in the last column:

| Key type      | Binding                               | Use                                                                | `scope` value |
| ------------- | ------------------------------------- | ------------------------------------------------------------------ | ------------- |
| App key       | One registered application            | Login code exchange, standard calls, premium calls, and `usage()`. | `model`       |
| Read-only key | The business, across its applications | `GET /v1/business/info` business reporting reads.                  | `reporting`   |

An App key does not sign in a personal user. Managed calls also need that
user's session. A Read-only key cannot be used for model calls, and an App
key cannot read business reports.

## Create and store a key

1. Choose the key type. For an App key, select its registered application.
2. Create the key and copy the returned secret immediately.
3. Store it in your server's secret manager. For model calls, the SDK reads
   `ENLITT_SECRET_KEY` unless you pass `secretKey` explicitly.

**The raw secret is returned exactly once.** Later dashboard views show only
metadata, including key type, environment, prefix, status, and timestamps.
If you lose the secret, rotate the key.

## Rotate or revoke

Rotation replaces the secret while preserving the key identity, type, and
application binding. Store the new secret and update your server configuration.
Revocation disables the key; calls using it will fail authentication.

Key management happens in the dashboard or the CLI. The SDK does not export
the dashboard's key-management functions as public APIs. Creating, rotating,
and revoking a key needs the key-management permission, which today only the
business owner holds (see [Business account FAQ](/docs/business-account.md)), and
a recent sign-in approval.

## From the CLI

The CLI writes the secret straight into a file you name, so it never appears in
a terminal, a chat, or a log. Add `--write-env`; without it the command refuses
before it creates anything.

```bash
# Create an App key for an application and store it in .env.local
npx enlitt key create --app <application_id> --name "production server" --write-env .env.local

# Create a Read-only key (written as ENLITT_REPORTING_KEY)
npx enlitt key create --scope read-only --name "reporting job" --write-env .env.local

# List key metadata (never a secret), then rotate or revoke
npx enlitt key list --app <application_id> --json
npx enlitt key rotate <key_id> --write-env .env.local
npx enlitt key revoke <key_id> --confirm
```

Rotating a `live` key and every revocation need `--confirm`, and a coding agent
must have your explicit yes before it passes it. Rotation prints when the old
key stops working (`previous_key.expires_at`), so you know how long the deployed
application may keep the old value. See [the CLI](/docs/cli.md) for every flag.

## Keep the Read-only key separate

If the same server makes model calls and reads reports, use different secrets.
Keep `ENLITT_SECRET_KEY` for the App key and send the Read-only key from
`ENLITT_REPORTING_KEY` to `GET /v1/business/info`. See
[Business reporting](/docs/business-reporting.md).

Never put either secret in browser code, a public environment variable, logs,
or analytics. Keep test and live credentials separate.