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

# The API Key object

> Reference for API key credentials — secret, publishable, and restricted keys with permission scopes, expiration, and revocation.

API keys are the credentials your servers and the browser send in the `Authorization: Bearer` header. They are created in the dashboard's **Settings → API Keys**, stored as SHA-256 hashes, and shown exactly once at creation.

## Key types

| Type        | Prefix                    | Trust boundary | Capabilities                                            |
| ----------- | ------------------------- | -------------- | ------------------------------------------------------- |
| Secret      | `sk_live_…` / `sk_test_…` | Server         | Full access, or the explicit permission list you assign |
| Restricted  | `rk_live_…` / `rk_test_…` | Server         | Only the permissions you grant                          |
| Publishable | `pk_live_…` / `pk_test_…` | Browser        | Read-only, client-safe endpoints only                   |
| Legacy      | `api_…`                   | Server         | Full REST surface; accepted by the general routes today |

The prefix also encodes the environment: `*_live_*` for production, `*_test_*` for development. See [Authentication](/api/authentication) for the full key model and the endpoint auth matrix.

## API key object

```json theme={null}
{
  "id": "key_abc123",
  "name": "Production backend",
  "prefix": "sk_live_9fK2wX7…",
  "description": "Billing service keys",
  "type": "SECRET",
  "permissions": ["tokens.create", "usage.consume"],
  "environmentMode": "PRODUCTION",
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "revokedAt": null,
  "lastUsedAt": "2026-09-17T10:00:00.000Z",
  "createdAt": "2026-08-01T00:00:00.000Z"
}
```

| Field             | Type           | Description                                                              |
| ----------------- | -------------- | ------------------------------------------------------------------------ |
| `id`              | string         | Key record ID (`key_…`)                                                  |
| `name`            | string         | Human-readable name                                                      |
| `prefix`          | string         | First 16 characters of the raw key — used to identify the key in logs/UI |
| `description`     | string \| null | Optional description                                                     |
| `type`            | string         | `SECRET`, `PUBLISHABLE`, or `RESTRICTED`                                 |
| `permissions`     | string\[]      | Permissions granted to the key (restricted keys always have ≥ 1)         |
| `environmentMode` | string         | `DEVELOPMENT` or `PRODUCTION`                                            |
| `expiresAt`       | string \| null | Expiry timestamp; `null` = does not expire                               |
| `revokedAt`       | string \| null | When the key was revoked                                                 |
| `lastUsedAt`      | string \| null | Last successful authenticated call                                       |
| `createdAt`       | string         | Creation timestamp                                                       |

<Warning>
  The API **never returns the full raw key** after creation. The raw value (`sk_…`) is returned only once from the create response. If you lose it, revoke and recreate.
</Warning>

## Managing keys in the Dashboard

API keys are created, inspected, and revoked directly within the Provider Dashboard:

1. Navigate to **Settings → API Keys** in your ArcenPay Dashboard.
2. Click **Create Secret Key** or **Create Publishable Key**.
3. For secret or restricted keys, specify the name, expiration window (optional), and granted permissions (e.g. `tokens.create`, `usage.consume`).
4. Copy and securely store the raw key. ArcenPay stores only the SHA-256 hash and will never display the raw secret again.
5. To invalidate a compromised key immediately, click **Revoke Key** in the dashboard.

<Note>
  Root API keys are provisioned exclusively through the dashboard to guarantee administrative security and multi-factor authorization. Automated services do not provision root API keys via programmatic REST.
</Note>

## Programmatic token generation

For customer sessions, client embeds, and delegated permissions, ArcenPay provides two dedicated REST endpoints callable using your Secret or Restricted API keys:

1. **[Create a temporary access token (`POST /api-keys/tokens`)](/api-reference/credentials/post-api-keys-tokens)**: Mints a short-lived `arc_tok_…` token (60–900s TTL) scoped to a single company. Ideal for passing to `ArcenEmbed` or client-side widgets without leaking your root secret key.
2. **[Create an access token (`POST /access-tokens`)](/api-reference/credentials/post-access-tokens)**: The programmatic backend behind the SDK `identify()` method. Upserts the customer's company and user records in one call and returns a customer session token.

Explore each endpoint's parameters, schema, and interactive testing console in the sidebar.

## Permission catalog

| Permission            | Grants access to                                |
| --------------------- | ----------------------------------------------- |
| `entitlements.read`   | `GET /api/v1/check`, `GET /api/v1/entitlements` |
| `usage.consume`       | `POST /api/v1/usage/consume`                    |
| `customers.read`      | Read-only company/event endpoints               |
| `companies.write`     | Company writes                                  |
| `payments.write`      | Payment-link/checkout writes                    |
| `subscriptions.write` | Subscription activation/lifecycle               |
| `tokens.create`       | `POST /api/v1/api-keys/tokens`                  |

## Best practices

* Name keys by environment and purpose (`production-billing`, `staging-webhook-test`).
* Set an expiry for short-lived projects; rotate on a schedule.
* Use restricted keys with only the permissions each service needs.
* Store raw keys in a secret manager — the platform stores only hashes.

## Related

* [Authentication](/api/authentication) — full key model, prefixes, and endpoint auth matrix
* [Create an access token](/api-reference/credentials/create-an-access-token-identify) — `identify()` / server-minted JWT session tokens
* [Rate limits](/api/rate-limits) — per-key request windows