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

# Authentication

> Authenticate your API requests to the Payment SDK

## Bearer Token Authentication

All server-side Grain API requests require your API key passed as a Bearer token in the `Authorization` header.

```bash theme={null}
curl -X POST https://api.pay.grain.inc/payment-sessions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"amount": "50.00", "currency": "USD"}'
```

```typescript theme={null}
const response = await fetch("https://api.pay.grain.inc/payment-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CUBEPAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: "50.00", currency: "USD" }),
});
```

## Credential Types

Grain uses two types of credentials for different contexts:

| Credential                                          | Use                      | Scope                                                                 |
| --------------------------------------------------- | ------------------------ | --------------------------------------------------------------------- |
| **API Key** (`CUBEPAY_API_KEY`)                     | Server-side only         | Create payment sessions, authenticate with the Grain API              |
| **Merchant ID** (`NEXT_PUBLIC_CUBEPAY_MERCHANT_ID`) | Client-side              | Initialize the SDK, identify your merchant account                    |
| **Session Token** (`paymentSessionToken`)           | Client-side, per session | Authorize SDK operations and session retrieval for a specific payment |

<Warning>
  Your **API key** is a server-side secret. Never expose it in client-side code, public repositories, or frontend bundles. If you suspect a key has been compromised, rotate it immediately in the [Grain Dashboard](https://dashboard.grain.inc).
</Warning>

## Session Token Authentication

When you create a payment session, the API returns a `paymentSessionToken`. This short-lived token is scoped to a single session and used for:

* Opening the SDK payment modal (`sdk.open()`)
* Retrieving session details (`GET /api/payment-sessions`)

```typescript theme={null}
// Server creates the session
const session = await createPaymentSession({ amount: "50.00", currency: "USD" });

// Client uses the session token
const result = await sdk.open({
  paymentSessionId: session.paymentSessionId,
  paymentSessionToken: session.paymentSessionToken,
});
```

<Note>
  Session tokens expire automatically and cannot be reused across sessions. Each `POST /payment-sessions` call returns a fresh token.
</Note>

## Rotate API Keys

<Steps>
  <Step title="Generate a new key">
    In the [Grain Dashboard](https://dashboard.grain.inc), go to **Settings > API Keys** and generate a new key.
  </Step>

  <Step title="Update your application">
    Replace `CUBEPAY_API_KEY` in your environment variables and deploy.
  </Step>

  <Step title="Revoke the old key">
    Once your application is running with the new key, revoke the old one in the dashboard.
  </Step>
</Steps>

## Next Steps

Explore the full list of [Endpoints](/payment-sdk/api-reference/endpoints) available in the Payment SDK API.