# Authentication

Source: https://docs.orbytelabs.com/authentication

Create application-scoped secret keys and give each service the permissions it needs.

All Credit API operations require a secret key except `GET /v1/openapi.json`. Send the key in the `Authorization` header:

```sh
curl --fail-with-body "https://api.orbytelabs.com/v1/application" \
  -H "Authorization: Bearer $ORBYTE_API_KEY"
```

The key selects the organization and application. Requests cannot override them with an `orgId` or `appId` field. The same identity in Development and Production has separate wallets and balances.

## Create a key [#create-a-key]

Select the target application in the Credit dashboard. Open **Developers → API keys → Create key**, give the key a name, and choose a preset. Copy the secret shown after creation. Credit does not show the full secret again.

Key management requires organization admin access or the corresponding organization permission. You cannot grant scopes that your own account cannot use.

| Preset              | Use it for                                                          |
| ------------------- | ------------------------------------------------------------------- |
| Setup and ingestion | Initial catalog setup, wallet funding, reads, checks, and tracking. |
| Ingestion           | A server that only checks access and tracks usage.                  |
| Read only           | Reporting on catalog, subscriptions, wallets, and deposits.         |

An ingestion key cannot deploy prices, read wallet records, or fund a wallet. A check returns the relevant balance under `events:ingest`; a separate `getWallet` request needs `wallets:read`.

## Permissions [#permissions]

| Permission            | Operations                                                                           |
| --------------------- | ------------------------------------------------------------------------------------ |
| `credits:read`        | Read credits and identify the key's application.                                     |
| `credits:write`       | Create or update credits.                                                            |
| `features:read`       | Read features.                                                                       |
| `features:write`      | Create or update features.                                                           |
| `wallets:read`        | List wallets and read balances.                                                      |
| `wallets:write`       | Create wallets and set their billing periods.                                        |
| `deposits:read`       | Read a wallet's top-up history.                                                      |
| `deposits:write`      | Deposit credits, creating the wallet if needed.                                      |
| `plans:read`          | Read plan definitions and synchronization status.                                    |
| `plans:write`         | Create and revise plan definitions.                                                  |
| `subscriptions:read`  | Read a wallet's subscription.                                                        |
| `subscriptions:write` | Create checkout or portal sessions, change plans, and schedule or undo cancellation. |
| `events:ingest`       | Check affordability and track usage.                                                 |

Use a setup key for catalog deployment and keep it separate from a runtime ingestion key. A payment handler that calls `topup` also needs `deposits:write`. Hosted subscription checkout and billing management need `subscriptions:write`; paid top-up checkout also needs `subscriptions:write`. Existing keys do not gain these permissions automatically.

## SDK credentials [#sdk-credentials]

The SDK reads your API key when a request is made and connects to `https://api.orbytelabs.com` automatically:

```dotenv
ORBYTE_API_KEY=cr_secret_your_key
```

No API URL variable is required. The CLI loads `.env.local` beside `orbyte.config.ts`; existing process variables take precedence. In your application, load environment variables through your server runtime or framework.

You can override credentials for one call:

```ts
import { check } from "@orbytelabs/credit";

const access = await check("api-call", "customer_123", {
  apiKey: process.env.ORBYTE_API_KEY,
});
```

Keep keys and callback pricing on your server. Resolve wallet identities from your authenticated user or organization. Accepting an arbitrary identity from a browser would let that caller spend someone else's wallet. A secret key with `events:ingest` can submit the resolved amount for callback-priced features.

## Rotate or revoke a key [#rotate-or-revoke-a-key]

Create a replacement key in the same application, update the relevant server environment, and verify requests with it. Then revoke the old key in Developers. Revoked keys stop working. The catalog, wallets, and ledger history remain in the application.

A missing or invalid key returns `401`. A key without the operation's permission returns `403`. See [errors and retries](/errors) for response formats.