Authentication
Send your API key in the X-SAMITA-API-KEY header, and understand what makes a key valid.
이 콘텐츠는 아직 번역되지 않았습니다.
Every request must carry an API key. Create one first — see Create an API key.
Send the key in a header
Section titled “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 |
curl https://quote.samita.io/api/public/v1/ping \ -H "X-SAMITA-API-KEY: sqt_your_key_here"You do not need to say which store you mean. The key already identifies it.
Server-to-server only
Section titled “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
Section titled “When a key is accepted”On every request the API checks that:
- a key was sent, and it exists
- it has not been revoked
- it has not expired
- the store still has the app installed
- the store’s plan includes the Public API
- 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
Section titled “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
Section titled “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
Section titled “Next steps”- Make your first call — check the key works
- Errors — every error and what to do