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:
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
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
| 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
The SDK reads your API key when a request is made and connects to https://api.orbytelabs.com automatically:
ORBYTE_API_KEY=cr_secret_your_keyNo 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:
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
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 for response formats.