Authentication

Authenticate Store API calls with an app or Store Admin bearer token.

Store API authentication is Bearer-only. Cookies, HTTP Basic authentication, and API keys in query parameters are not accepted.

http

GET /api/2025-01/reference/currencies HTTP/1.1
Host: api-store.tringify.com
Authorization: Bearer YOUR_STORE_API_TOKEN

Token types#

Prefix	Issued by	Lifetime	Access
`tpat_`	App installation	Until the app is uninstalled or the token is replaced	The scopes the merchant approved for the installation.
`tast_`	App Bridge session exchange	15 minutes	The scopes requested and granted during the session exchange, limited by the installation and the screen that asked. Sessions opened by a staff member are also limited by that staff member's permissions.
`tsat_`	Store Admin	Until expiry, rotation, or revocation	The scopes selected when the token was created.

Getting a token#

App tokens (`tpat_`)#

An app receives its token when a merchant installs it. The merchant reviews and approves the scopes requested by the app release they install. Tringify then creates the installation's tpat_ token and sends it to your app's webhook endpoint in the app.installed event, as data.access_token, together with the granted data.scopes and the store_id.

Set the webhook endpoint and signing key in the Developer Portal under your app's Webhooks settings before your app is installed. Install, token rotation, and uninstall events are always sent.
Verify the request signature, then store the token on your server, keyed by store_id. The token is not shown in Store Admin and cannot be retrieved later.
When the merchant approves changed scopes or the token is rotated, app.token_rotated delivers a replacement token. Start using it and discard the previous one.
When the merchant uninstalls the app, app.uninstalled is sent and the token stops working.

See App webhooks for the payloads and signature verification, and Install lifecycle for what uninstalling changes.

Session tokens (`tast_`)#

An embedded app running inside Store Admin calls bridge.getSessionToken() to get a short-lived tast_ token for the scopes one screen needs; see App Bridge authentication. Request another token when one expires, and never store it.

Store Admin tokens (`tsat_`)#

Merchants create Store Admin tokens in Store Admin under Settings > API Tokens for scripts and private server integrations. Select only the scopes the integration needs. Copy the token when it is shown; it cannot be revealed again later.

Scopes#

Each endpoint names its required scope. Write scopes include the matching read scope where the scope catalog says so. Use GET /api/2025-01/scopes to read the current catalog shown during app installation.

Store API scopes use an underscore, such as read_products or write_orders.

An app that needs additional scopes must request them in a new release, which the merchant approves. Store Admin tokens keep the scopes selected by the merchant until they are updated, rotated, or revoked.

Token lifecycle#

tpat_ and tast_ stop working when the app is uninstalled or the app itself is no longer active. Reducing the installation's approved scopes also reduces the scopes existing tokens can use.
tast_ expires 15 minutes after it is issued. Request a new session token through App Bridge.
tsat_ stops working at its optional expiry or immediately after rotation or revocation. An expiry, when set, can be at most one year after creation.

Authentication errors#

Status	Code	Meaning
401	`UNAUTHORIZED`	The Authorization header is missing.
401	`INVALID_TOKEN`	The Authorization header is not `Bearer` followed by a token, or the token does not start with `tpat_`, `tast_`, or `tsat_`.
401	`STORE_ADMIN_TOKEN_RUNTIME_UNAUTHORIZED`	The token was not accepted. Despite its name, this code is returned for every token type; see below.
402	`SUBSCRIPTION_REQUIRED`	The store does not have an active or trialing subscription.
403	`STORE_API_SCOPE_REQUIRED`	The token does not grant the scope required by the endpoint.
403	`API_VERSION_UNSUPPORTED`	The token is pinned to an API version that is no longer served.
429	`RATE_LIMITED`	The rate limit was reached. Wait for `Retry-After` before retrying.

When a token is not accepted#

STORE_ADMIN_TOKEN_RUNTIME_UNAUTHORIZED is returned for app, session, and Store Admin tokens alike. The response does not say why a token was refused, so a guessed or leaked token reveals nothing. It is returned when:

an app token (tpat_) was replaced by rotation, or the app was uninstalled or is no longer active;
a session token (tast_) is more than 15 minutes old, or its app installation has ended;
a Store Admin token (tsat_) has expired, was rotated, or was revoked;
the token does not exist, for example because it was copied incorrectly;

Do not retry the same token. For tast_, request a new session token. For tpat_, use the replacement from app.token_rotated, or treat the installation as ended after app.uninstalled. For tsat_, ask the merchant to create a new token.

Branch on error.code, not error.message. See Errors for the common response format and Rate limits for request limits.

Manage merchant-created tokens#

Only the store owner can manage Store API tokens under Settings > API Tokens in Store Admin or the mobile app. Choose a descriptive name, at least one scope, a supported API version and an expiry. The full tsat_ secret is returned once; it cannot be retrieved from the token list or details later. Store it on your server and send it only as Authorization: Bearer. Do not embed it in a storefront, mobile client, URL, repository or log.

Changing scopes changes the access available to subsequent requests using the same secret. Write scopes include the matching read scope. If a scope is removed, requests that need it return 403 STORE_API_SCOPE_REQUIRED. Ask the merchant to review the required access rather than repeatedly retrying the refused operation.

Rotation replaces the secret and immediately invalidates the old one. It preserves the token’s scopes, pinned API version and expiry. Rotation does not renew or extend expiry. Revocation also invalidates the token. After either action, an integration using the old secret receives 401 STORE_ADMIN_TOKEN_RUNTIME_UNAUTHORIZED.

To change expiry or API version, create a replacement token, update your integration, verify a request, and revoke the previous token. A separate replacement allows a controlled overlap; rotation does not. Send requests to the Store API version the token is pinned to and check the X-Tringify-API-Version response header.

The management pages support search, pagination, details, scope edits, single-token revocation and revocation of selected rows. A one-time secret remains only in the current view; leaving or reloading it does not reveal it again. If an issued secret is lost, create a replacement and revoke the unused token. The token count and limits are shown in the management page.