# Authentication

All Gett API requests must be authenticated using a Bearer token in the `Authorization` header.

```http
Authorization: Bearer YOUR_API_KEY
```

## Getting Your API Key

Your partner account is provisioned by Gett during onboarding — account setup is not self-serve. Contact our partnerships team to get started.

Once onboarded, members of your organization can create, rotate, and manage API keys from the [Developer Portal](/settings/api-keys).

## Environments

Sandbox and production share **one base URL** — your API key determines the environment. Each key is bound to a single environment, and a key from one environment will not act on the other's data.

| | |
|-------------|----------|
| **Base URL** | `https://api.gett-tech.com` (all environments) |
| **Environment** | Determined by your API key — Live or Sandbox |

There is **no separate sandbox host**. Provision a sandbox key to develop and test against sandbox stores; swap it for your production key to go live — the base URL never changes. Sandbox rate limits are **5x higher** than production to give you room during development.

## Key Management

Manage your API keys from the [Developer Portal](/settings/api-keys). You can:

- **Create** new keys with optional descriptions and expiration dates
- **Rotate (Roll)** existing keys — generates a new key value while keeping the same key entry
- **Delete** compromised or unused keys immediately

### Organization Scoping

API keys are scoped to your **partner organization**, not individual user accounts:

- All organization members can create, rotate, and delete keys
- Rate limits are shared across all keys belonging to the same organization
- Revoking a key affects anyone using it — coordinate with your team before deleting

## Security Best Practices

:::caution
Your API key is a secret. Never expose it in client-side code, mobile apps, or public repositories.
:::

- **Store keys securely** — Use environment variables or a secret manager, never hardcode in source
- **Never commit keys** — Add credential files to `.gitignore` and audit your repository
- **Rotate periodically** — Use the portal's Roll feature to rotate keys without downtime
- **Separate by environment** — Use distinct keys for sandbox and production
- **Server-side only** — Always make API calls from your backend; never from browsers or mobile apps

## Error Responses

If authentication fails, the API returns a `401 Unauthorized` response in [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) format:

```json
{
  "type": "https://developer.gett-tech.com/errors/UNAUTHENTICATED",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication required. Provide a valid API key (Bearer zpka_...).",
  "instance": "/v1/marketfront/stores/discover",
  "requestId": "req_abc123",
  "errorCategory": "authentication",
  "retryable": false
}
```

Common causes:
- Missing `Authorization` header
- Malformed header (e.g., missing `Bearer` prefix)
- Expired or revoked API key

A `401` is **not retryable** — fix the credential issue before retrying.

## Consumer Authentication

The API key authenticates **your platform** to Gett. It does not identify the **end user** placing an order — that's a separate concern.

Session creation is a server-to-server call authenticated with your API key. The result is a short-lived JWT (session token) you pass to the Marketfront SDK or send to your frontend to call session-gated endpoints directly.

**Per-partner identity uniqueness.** Each partner has its own user namespace. The same end user signing in on two different partner storefronts resolves to **two distinct Gett accounts** — carts, saved addresses, payment methods, and order history are never shared between partners.

## Consumer Sign-in

The mechanics of resolving a consumer's identity depend on which integration path you're using:

- **Marketfront SDK partners.** The embed manages sign-in inside its own UI. When an anonymous user reaches a checkout action, the embed prompts for sign-in; partners do not host the trigger. See [Sessions](/distribution-partners/marketfront-sdk/guides/sessions) in the SDK guide.
- **Raw Marketfront API partners.** All partner API calls authenticate with a server-side API key. The session/identity layer is internal to the SDK and is not part of the partner API surface.

## Webhook Authentication

For inbound webhooks (Gett calling your system), authentication uses HMAC-SHA256 signatures rather than API keys. Each webhook request includes a `Signature` header (plus `Timestamp` for replay protection and `API-Version` for the protocol version) that you must verify before processing.

See [Webhooks](/distribution-partners/shared-guides/webhooks) for signature verification details and code examples.