# Authentication

> Published: 2026-08-06
> Updated: 2026-08-06
> Canonical: https://finalpos.com/docs/authentication

Every Final POS API request needs an API key. Use a company key in the x-api-key header for standard resource endpoints, or an organization key in the x-org-api-key header for org-level company management. Create keys under Settings > API Keys in manage.finalpos.com or scale.finalpos.com, granting only the permissions each integration needs.

Every request to the Final POS API must include an API key. Keys are scoped with permissions so you can grant only the access each integration needs.

Final POS exposes **two kinds of keys**, each scoped to a different layer of the platform:

| Key                      | Header          | Scope                                           | Used for                                                           |
| ------------------------ | --------------- | ----------------------------------------------- | ------------------------------------------------------------------ |
| **Company API key**      | `x-api-key`     | A single company                                | Day-to-day resource operations (products, customers, orders, etc.) |
| **Organization API key** | `x-org-api-key` | A whole organization (across all its companies) | Org-level operations — managing and onboarding companies           |

Pick the key that matches the endpoint you are calling. Each endpoint accepts **only one** of the two — sending both headers on the same request is rejected.

## Company API Key

Use a company API key for the standard `/v1/api/...` resource endpoints documented in the **API Reference**.

### Creating a Company API Key

1. Go to [manage.finalpos.com](https://manage.finalpos.com).
2. Navigate to **Settings > API Keys**.
3. Click **Create API Key**.
4. Give the key a descriptive name (e.g. "WooCommerce Sync", "Inventory Script").
5. Select the **permissions** the key needs (see [Permissions](#permissions)).
6. Copy the key — you will not be able to see it again.

### Sending the Key

Pass your company API key in the `x-api-key` header on every request:

```bash
curl -X GET https://api.finalpos.com/v1/api/customers \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Organization API Key

Use an organization API key for `/v1/api/organization-api/...` endpoints — the ones documented in the **Organization API** reference. These cover org-level workflows such as onboarding a new company, managing plans across companies, and other company management operations.

### Creating an Organization API Key

1. Go to [scale.finalpos.com](https://scale.finalpos.com).
2. Navigate to **Settings > API Keys**.
3. Click **Create API Key**.
4. Give the key a descriptive name (e.g. "Onboarding Service").
5. Select the **permissions** the key needs (see [Permissions](#permissions)).
6. Copy the key — you will not be able to see it again.

### Sending the Key

Pass your organization API key in the `x-org-api-key` header:

```bash
curl -X POST https://api.finalpos.com/v1/api/organization-api/company/company-workflow/onboard/ORGANIZATION_ID \
  -H "x-org-api-key: YOUR_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

> Do **not** send `x-api-key` and `x-org-api-key` on the same request. The API requires exactly one of the two and will reject requests that include both.

## Permissions

Each API key — company or organization — is scoped to specific resource permissions. Only grant what the integration actually requires.

Permissions are mapped to HTTP verbs:

| Verb            | Required permission |
| --------------- | ------------------- |
| `GET`           | `read`              |
| `POST`          | `create`            |
| `PUT` / `PATCH` | `update`            |
| `DELETE`        | `delete`            |

For example, an integration that imports products only needs `create` access to Products, while a reporting dashboard only needs `read` access to Orders and Transactions. An org key used solely for company onboarding only needs `create`.

## Key Management

- **Rotate keys** periodically by creating a new key, updating your integration, then deleting the old one.
- **Revoke a key** immediately if it is compromised — delete it from the relevant API Keys page.
- **Use separate keys** for each integration so you can revoke one without affecting others.