Docs

Authentication

Two kinds of credential, one header. A secret key lives on your server. A client token lives in your app and acts for one user.

Checked against the API and the live OpenAPI on 2026-10-21.

The base URL

There is one base URL: https://api.giftingstack.com. The environment (live or test) is chosen by the key you send, not by the host.

The two credentials

	Secret key	Client token
Looks like	`gs_live_…` or `gs_test_…`, then 32 letters and digits	`gs_ct_…`
Lives in	Your server only. Never in an app, a web page or a repository.	Your app. Safe to ship to the user's device.
Created	In the dashboard (API keys). Shown once.	By your server, with `POST /v1/client-tokens`.
Endpoints	`/v1/*`	`/v1/client/*` only
Can do	Everything in the API for your project and that environment.	Read the catalog and its own balance, read received gifts, leaderboards and walls, send a gift as its own user. Never credit or debit.
Lifetime	Until you revoke it, or until its expiry date if you set one when creating it.	60 seconds to 24 hours, one hour by default.

A secret key sent to a /v1/client/* endpoint is refused on purpose, and a client token sent to /v1/* is not a valid key. See Client tokens for minting, refreshing and revoking.

The header

Send the credential as a bearer token on every request:

curl https://api.giftingstack.com/v1/gifts \
  -H "Authorization: Bearer $GS_KEY"

Requests with a body use Content-Type: application/json and are limited to 16 KB (413 payload_too_large). The endpoints that move coins also need an Idempotency-Key header: see Idempotency.

Headers you get back:

Header	When	Meaning
`X-Request-Id`	Every response	The id of this request. Quote it when you contact support. The same id is in the error body as `request_id`.
`Idempotent-Replayed: true`	A replayed request	The answer is the stored one from the first call.
`Retry-After`	`429`, and some `503`	Seconds to wait before you try again.
`WWW-Authenticate`	`401`	Tells the client which kind of bearer credential the endpoint expects.

Keys

Create and revoke keys in the dashboard, under your project, API keys. The key is shown once. GiftingStack stores only its SHA-256 hash, so a lost key cannot be recovered: create a new one.
There is no API to create keys. To rotate: create a new key, deploy it, then revoke the old one.
Revoking a key, or the key expiring, takes effect within about 30 seconds (keys are cached for 30 seconds). Revoking a key also ends every client token it minted.
Keep keys out of logs and source control. If a key leaks, revoke it first, then look at the ledger of the affected users.

Live and test

Each project has two separate environments. A gs_test_ key only ever sees test data, a gs_live_ key only live data. They have their own users, balances, gift catalog, ledger and events, and they never mix.

	Test	Live
Plan needed	Every plan, including the free Test plan	Starter or above. Creating a live key on the Test plan is refused with `403 plan_required` in the dashboard, and a live key on the Test plan can only read (it can still delete users, change leaderboard visibility and revoke client tokens). Only the project owner creates live keys.
Limits	50 users and 5,000 operations a month. See Rate limits.	No such caps. A request limit per project environment that follows your plan.
Can be suspended	Never	Yes, under the rules in the Terms (section 11). See Errors.

When authentication fails

Status	`type`	Cause	What to do
401	`invalid_api_key`	No `Authorization` header, not `Bearer <key>`, a client token, an unknown or malformed key, a revoked or expired key, or the project is scheduled for deletion. The message says which.	Check the key and the environment. Do not retry the same request.
401	`invalid_client_token`	On `/v1/client/*`: missing, malformed or expired token, a secret key sent by mistake, a revoked token, or the key that minted it is no longer valid.	Mint a new token on your server and retry once.
403	`project_suspended`	The live environment is suspended. For a secret key, `details.reason` says why; a client token gets only "This app is temporarily unavailable.", never the reason.	Contact support@giftingstack.com.
429	`rate_limited`	Too many requests, or too many failed authentications from one IP address (valid credentials never count against the IP limit).	Wait `Retry-After` seconds. See Rate limits.

Questions or something unclear? support@giftingstack.com.