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

# Nymble Commerce API Authentication: Tokens, API Keys & Roles

> Learn how to obtain access tokens and API keys for the Nymble Commerce API, pass credentials in requests, and handle common authentication errors.

Nymble Commerce supports two authentication methods. Use **credential-based login tokens** for user-facing applications where your server exchanges credentials for a scoped token. Use **`x-api-key` header authentication** for machine-to-machine (M2M) integrations where a pre-issued API key is passed directly in every request. Choose the method that matches your integration architecture — both grant access to the same API surface, scoped to your organization.

***

## Login Token Authentication

Use login token authentication when your application authenticates on behalf of a user or customer session. Your server exchanges your `OrgCode`, `ClientId`, and `ClientSecret` for a short-lived access token, then passes that token in the `x-api-key` header on all subsequent requests.

### Endpoint

```text theme={null}
POST /api/auth/login
```

### Request body

<ParamField body="OrgCode" type="string" required>
  Your organization code. This identifies which Nymble Commerce tenant you are authenticating against. Example: `org_52a3021e813`.
</ParamField>

<ParamField body="ClientId" type="string" required>
  Your client ID. Issued when your API credentials are provisioned. Acts as the username component of your credential pair.
</ParamField>

<ParamField body="ClientSecret" type="string" required>
  Your client secret. Issued alongside your `ClientId`. Treat this as a password — never expose it in client-side code or public repositories.
</ParamField>

### Response fields

<ResponseField name="AccessToken" type="string">
  A signed access token. Pass this value in the `x-api-key` header of every subsequent API request. The token encodes your organization context and role claims so you don't need to pass them separately.
</ResponseField>

<ResponseField name="TokenType" type="string">
  The token scheme. Always returns `"api-key"`.
</ResponseField>

<ResponseField name="ExpiresIn" type="integer">
  The token's lifetime in seconds. Typically `86400` (24 hours). Cache the token and reuse it until it approaches expiry rather than requesting a new one on every call.
</ResponseField>

### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "OrgCode": "org_52a3021e813",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret"
  }'
```

### Example response

```json theme={null}
{
  "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJPcmdhbml6YXRpb25JZCI6IjY1OTA0OTM3NDU3MzE0MjIyYzNmMWNiNCIsIkN1c3RvbWVyTnVtYmVyIjoiQ1VTVDQ1NiIsIlByaWNlVGllciI6Ildob2xlc2FsZSIsIkN1cnJlbmN5Q29kZSI6IlVTRCIsInJvbGUiOiJDdXN0b21lciIsImV4cCI6MTczNTY4OTYwMH0.fake_signature",
  "TokenType": "api-key",
  "ExpiresIn": 86400
}
```

### Using the token

Pass the `AccessToken` value in the `x-api-key` header on every subsequent request:

```bash theme={null}
curl -X GET https://api.achievemomentum.com/api/products \
  -H "x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept: application/json"
```

<Note>
  The `/api/auth/login` endpoint is rate-limited to **10 requests per minute** per `ClientId`. If you exceed this limit, you'll receive a `429 Too Many Requests` response. Cache your token and reuse it for its full `ExpiresIn` duration to stay well within this limit.
</Note>

***

## API Key Authentication

For server-to-server integrations, automated pipelines, and backend services, use a pre-issued API key instead of the credential login flow. Pass your API key directly in the `x-api-key` request header.

```bash theme={null}
curl -X GET https://api.achievemomentum.com/api/products \
  -H "x-api-key: your-api-key" \
  -H "Accept: application/json"
```

API keys are scoped to your organization and bypass the credential login flow entirely — there's no expiry to manage and no login call required. This makes them ideal for:

* ERP and accounting system integrations
* Scheduled data sync jobs
* Webhook processors and event-driven pipelines
* Internal tooling that runs with elevated or admin-level access

<Note>
  Contact your Nymble Commerce account administrator to obtain or rotate your organization's API key. API keys carry the same organizational scope as a login token but are not tied to an individual user session.
</Note>

***

## Token claims

When you authenticate via `POST /api/auth/login`, the returned `AccessToken` encodes your organization context. The Nymble Commerce API reads these claims on every request, so you don't need to pass organization context explicitly in most endpoints.

Key claims carried in the token:

| Claim            | Type   | Description                                                                                                                                        |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OrganizationId` | string | The unique ID of your Nymble Commerce organization. Used to scope all data access — products, customers, orders, and more.                         |
| `CustomerNumber` | string | The customer account number associated with the authenticated user. Scopes cart and order operations to that customer.                             |
| `PriceTier`      | string | The pricing tier assigned to the customer (e.g., `Wholesale`, `Retail`). Applied automatically when listing products and calculating order totals. |
| `CurrencyCode`   | string | The currency for this session (e.g., `USD`, `CAD`). Used to format prices consistently across catalog and order responses.                         |

These claims are populated when your API credentials are provisioned and enriched at login time.

***

## Authorization roles

Every Nymble Commerce user or integration is assigned a role that determines which API endpoints and resources are accessible. Roles are configured during account provisioning.

| Role         | Access level                                                                                                                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin**    | Full access to all organization resources: customers, products, orders, invoices, payments, settings, and analytics. Required for bulk operations, customer management, and organization configuration. |
| **Customer** | Access to their own account, the product catalog, their carts, and their order and invoice history. Cannot access other customers' data.                                                                |
| **SalesRep** | Access to the accounts and orders assigned to that rep. Can place and manage orders on behalf of assigned customers. Cannot access accounts outside their assignment.                                   |

<Note>
  Roles are set when your account is provisioned. To add, change, or remove roles for a user or integration credential, contact Nymble Commerce support.
</Note>

***

## Common authentication errors

| HTTP Status             | Error                            | Cause and resolution                                                                                                                                                              |
| ----------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`      | Missing or invalid credential    | Your request is missing the `x-api-key` header, the token is malformed, or the token has expired. Re-authenticate to get a new token and retry.                                   |
| `403 Forbidden`         | Insufficient role or permissions | Your token is valid but your role doesn't have access to the requested resource. Check that your role (Admin, Customer, SalesRep) is appropriate for the endpoint you're calling. |
| `429 Too Many Requests` | Rate limit exceeded              | You've exceeded 10 login requests per minute on `/api/auth/login`. Implement token caching to avoid repeated logins. Back off and retry after 60 seconds.                         |

***

## Security best practices

<Tip>
  **Never expose your `ClientSecret` in client-side code.** Your `ClientSecret` is equivalent to a password. Keep it server-side only — in environment variables or a secrets manager — and never commit it to source control or embed it in mobile apps or browser JavaScript.
</Tip>

<Tip>
  **Use API keys for server-to-server integrations.** For backend services, cron jobs, and ERP integrations, use a pre-issued API key via the `x-api-key` header rather than the credential login flow. API keys have no expiry to manage and avoid the overhead of token exchange.
</Tip>

<Tip>
  **Cache login tokens until near expiry.** A token is valid for `ExpiresIn` seconds (typically 86,400 seconds / 24 hours). Store it in memory or a short-lived cache and reuse it across requests. Refresh it only when it's within a few minutes of expiry. This keeps you well within the login rate limit and reduces latency.
</Tip>

<Warning>
  **Rotate credentials immediately if compromised.** If you suspect your `ClientSecret` or API key has been exposed, contact Nymble Commerce support to rotate your credentials. Previously issued tokens will be invalidated when credentials are rotated.
</Warning>