# Authentication

> Send your API key in the X-SAMITA-API-KEY header, and understand what makes a key valid.

App: SA Request a Quote, Hide Price (Shopify app by Samita)
Source: https://docs.samita.io/sa-request-a-quote/public-api/authentication
Last updated: 2026-11-18

Every request must carry an API key. Create one first — see [Create an API key](https://docs.samita.io/sa-request-a-quote/public-api/create-api-key).

## Send the key in a header

Use either header. Both do the same thing.

| Header | Example |
| --- | --- |
| X-SAMITA-API-KEY | X-SAMITA-API-KEY: sqt_your_key_here |
| Authorization | Authorization: Bearer sqt_your_key_here |

```bash
curl https://quote.samita.io/api/public/v1/ping \
  -H "X-SAMITA-API-KEY: sqt_your_key_here"
```

> **Warning**
>
> **Never put the key in the URL.** Keys sent as a query string (`?key=...`) are ignored, and the request fails with `unauthorized`. A URL ends up in logs, browser history and referrer headers.

You do not need to say which store you mean. The key already identifies it.

## Server-to-server only

The API refuses any request that carries an `Origin` header, which is what a browser adds to calls made from a web page. The error is `cors_not_supported`. Call the API from your server, a script or an automation tool, and keep the key out of anything customers can see.

## When a key is accepted

On every request the API checks that:

1. a key was sent, and it exists
2. it has not been **revoked**
3. it has not **expired**
4. the store still has the app installed
5. the store's plan includes the Public API
6. the key has the **permission** the endpoint needs

Revoking a key takes effect immediately.

| If this fails | Status | Error code |
| --- | --- | --- |
| No key sent | 401 | unauthorized |
| Unknown, revoked or expired key, or the app was uninstalled | 401 | invalid_api_key |
| Plan does not include the API | 403 | plan_upgrade_required |
| The API is not available for the store | 403 | not_available |
| Key lacks the permission | 403 | insufficient_scope |
| Request came from a browser | 403 | cors_not_supported |

## Permissions

Each endpoint needs one permission, called a **scope** in responses:

| Scope | Shown in the app as |
| --- | --- |
| quotes:read | Quotes — View |
| quotes:create | Quotes — Create |
| quotes:update | Quotes — Update |
| quotes:delete | Quotes — Delete |
| form:read | Quote form — View |

A request without the right scope returns `403 insufficient_scope` and names the missing permission. `GET /ping` needs no scope, so it works with any valid key.

## Repeated failures are blocked

Too many failed attempts from one IP address — 30 in a minute — return `429 rate_limited` with a `Retry-After` header. Fix the key before retrying in a loop.

## Next steps

* [Make your first call](https://docs.samita.io/sa-request-a-quote/public-api/make-first-call) — check the key works
* [Errors](https://docs.samita.io/sa-request-a-quote/public-api/errors) — every error and what to do
