---
title: "Authentication"
description: "Secret and publishable keys, environments, and the permissions a key carries."
image: "https://docs.ordercard.io/og.png"
---

> API Reference Index
> Fetch the complete API index at: https://docs.ordercard.io/api/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

Send a secret key as a bearer token on every request:

```bash
curl https://api.ordercard.io/v1/payment_methods \
  -H "Authorization: Bearer oc_sk_test_4Fq9…"
```

Keys belong to your **team**, not to a person, so they keep working when someone leaves. Create them in the dashboard under **Developers → API keys**. The full value is shown once; afterwards OrderCard shows its prefix and last four characters, like `oc_sk_test_4Fq9…9fQ2`, which is enough to match a key you find in a config file.

## Key types

| Key | Looks like | Used for |
| --- | --- | --- |
| Secret | `oc_sk_test_…`, `oc_sk_live_…` | Your server. Calls this API with the permissions you chose. Keep it out of web pages and mobile apps. |
| Publishable | `oc_pk_test_…`, `oc_pk_live_…` | The browser. Loads [hosted fields](/hosted-fields) on the websites you listed, and nothing else. |

A publishable key sent to this API is refused with `401`.

## Environments

Every key belongs to one environment, and so does everything it creates. A sandbox key only sees sandbox cards, gateways and transactions; a live key only sees live ones. There is no environment parameter: switching environments means switching keys.

- **Sandbox** is free. Use the [test cards](/testing) and the built-in test gateway, or your gateway's own sandbox account.
- **Live** charges real cards. It needs an active OrderCard plan; until then live requests answer `402` with the code `subscription_required`. Owners and admins choose a plan in the dashboard under **Team → Billing**.

## Permissions

A secret key carries a set of permissions. A request that needs a permission the key lacks answers `403 forbidden`.

| Permission | Allows |
| --- | --- |
| `payment_methods:read` | Reading vaulted cards. |
| `payment_methods:write` | Updating cards' details and retaining tokens. |
| `payment_methods:redact` | Destroying card numbers. |
| `payment_methods:pan` | Sending raw card numbers from your server ([vault a card](/api/payment-methods)). Only owners and admins can grant it. |
| `transactions:read` | Reading transactions. |
| `transactions:write` | Charging, authorizing, verifying, capturing, voiding and refunding, and surcharge quotes. |
| `gateways:read` / `gateways:write` | Reading or managing gateways. |
| `webhooks:read` / `webhooks:write` | Reading or managing webhook endpoints. |

When you create a key you can pick a preset: **Full access** (everything except `payment_methods:pan`), **Read only**, **Charge only** (`payment_methods:read` and both transaction permissions) or **Server-side tokenization**. A key can never get a permission its creator does not have.

## Unused keys

A secret key that makes no request for 30 days is turned off, so a key nobody uses cannot be misused. A week before, everyone on your team who manages API keys gets an email and a dashboard notification naming the key and the date; any request with the key before then starts its 30 days again. Once it is off, requests with it answer `401` until someone turns it back on under **Developers → API keys**, which gives it another 30 days. Publishable keys are never turned off for going unused.

## Failures

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No key, an unknown key, a revoked, expired or turned-off key, or a publishable key. |
| 402 | `subscription_required` | A live key on a team without an active plan. |
| 403 | `forbidden` | The key lacks the permission this endpoint needs. |

Source: https://docs.ordercard.io/api/authentication/index.mdx