# API Credentials

API credentials authenticate your server-to-server integration with the Fluxis REST API. Manage them in the Fluxis Dashboard at **`/app/api-keys`** (Owner and Admin roles only).

## Overview

Each credential pair consists of:

| Component | Description |
| --------- | ----------- |
| **API Key ID** | Public identifier sent on every protected request as `x-fluxis-api-key` |
| **API Secret** | Private secret used only for `POST /v1/auth/token` |

### Key ID format

| Environment | Prefix | Example |
| ----------- | ------ | ------- |
| Development | `fxs.dev.` | `fxs.dev.a1b2c3d4-...` |
| Staging | `fxs.stg.` | `fxs.stg.a1b2c3d4-...` |
| Production | `fxs.prd.` | `fxs.prd.a1b2c3d4-...` |

The secret is shown **once** when a key is created. Store it securely—you cannot retrieve it again from the dashboard.

## Create your first API key

Follow these steps after [signing up](/docs/merchant-integration/sign-up) and [enabling 2FA](/docs/developers/two-factor-auth):

1. Sign in to the Fluxis Dashboard:
   - Staging: [https://dashboard.stgfluxis.us](https://dashboard.stgfluxis.us)
   - Production: [https://dashboard.fluxis.us](https://dashboard.fluxis.us)
2. In the sidebar, open **Developers → API Keys** (path: `/app/api-keys`).
3. Click to **create a new key**.
4. Set a descriptive name (e.g. `staging-backend-integration`).
5. Assign roles **`read`** and **`write`** for a standard payment integration.
6. Complete the **2FA verification** challenge when prompted.
7. Copy the **API Secret** immediately and store it in your secrets manager—the dashboard will not show it again.
8. Note the **API Key ID** (`fxs.stg.*` or `fxs.prd.*`) for use as `x-fluxis-api-key` on protected requests.

::::warning
Only **Owner** and **Admin** collaborators can create API keys. See [Team & Roles](/docs/developers/team-and-roles) if you need access.
::::

Next: exchange the key and secret for a Bearer token—see [API Integration Guide — Authentication](/docs/developers/tutorials/api-integration-guide#step-2--authentication).

## Dashboard access

Open the Fluxis Dashboard and navigate to:

**`/app/api-keys`**

Available actions (Owner / Admin):

| Action | Description |
| ------ | ----------- |
| List keys | Paginated view of organization API keys |
| Create key | Generate a new key + secret (requires 2FA verification) |
| Update name / roles | Change display name or permission roles |
| Update allowed IPs | Restrict requests to specific IP ranges |
| Enable / Disable | Toggle key without deleting it |
| Delete | Permanently remove a key |

::::warning
Creating a new API key requires an active **two-factor authentication** challenge. Enroll at [`/app/user/2fa`](/docs/developers/two-factor-auth) before your first key creation.
::::

## API roles

Each key is assigned one or more API roles:

| Role | Typical permissions |
| ---- | ------------------- |
| `read` | Read-only access (list POS, get payment requests, list transactions) |
| `write` | Create and mutate resources (payment requests, refunds, webhooks) |

Roles are stored on the credential and enforced by the API authorization layer. Organization-scoped keys operate across accounts in your organization; account-scoped keys (when provisioned) are limited to a single account.

## Authentication flow

API credentials are **not** sent on every request directly. Exchange them for a short-lived Bearer token:

```bash
curl -X POST "https://api.fluxis.us/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "fxs.prd.YOUR_KEY_ID",
    "api_secret": "YOUR_API_SECRET"
  }'
```

Then call protected endpoints with **both** headers:

```bash
curl "https://api.fluxis.us/v1/pos?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"
```

::::note
Do **not** send `x-fluxis-api-key` on `POST /v1/auth/token`—only the JSON body with `api_key` and `api_secret`.
::::

### Token lifespan

- Access tokens expire after **1 hour**
- Request a new token before expiry
- Disabling a key immediately invalidates further use

## IP allowlisting

From `/app/api-keys`, you can restrict a key to specific source IP addresses or CIDR ranges. Requests from other IPs are rejected even with a valid token.

Leave allowlisting empty to permit any IP (not recommended for production).

## Security best practices

::::warning
Never embed API secrets in client-side code, mobile apps, or public repositories. Credentials belong on your backend only.
::::

1. **Use separate keys per environment** — dev, staging, and production should never share credentials
2. **Apply least privilege** — prefer `read` keys for reporting services; use `write` only where needed
3. **Disable unused keys** — disable or delete keys you no longer need
4. **Enable 2FA** — required for key creation; protects dashboard access
5. **Monitor `last_used_at`** — review key activity in the dashboard list

## Credential lifecycle

| Event | Effect |
| ----- | ------ |
| Key created | Secret shown once; key enabled by default |
| Key disabled | Token exchange and API calls fail |
| Key enabled | Normal operation resumes |
| Key deleted | Permanent; create a new key to replace |

::::info
Credential **rotation** (replacing a key while keeping the same logical identity) is handled through Fluxis support or by creating a new key, migrating integrations, and deleting the old key. There is no public "rotate secret in place" API today.
::::

## What credentials cannot do

- Dashboard login (collaborators use email/password + 2FA, not API keys)
- Automatic secret retrieval after creation

## Related documentation

- [Merchant Sign Up](/docs/merchant-integration/sign-up) — create account and enable 2FA
- [Two-Factor Authentication](/docs/developers/two-factor-auth) — required for key creation
- [Team & Roles](/docs/developers/team-and-roles) — who can manage API keys
- [API Integration Guide](/docs/developers/tutorials/api-integration-guide) — end-to-end integration