Authentication

Every Tanqory API call carries a JSON Web Token issued by the admin-api identity service. The same token is accepted by admin, store, and ai services. This page documents the format, how to obtain one, the operations that manage keys + sessions, and the errors you will see when the token is wrong.

The scheme

Tanqory declares exactly one security scheme:

Field	Value (from spec.components.securitySchemes)
Scheme name	bearer
Type	http
Bearer format	JWT

Every operation that requires auth carries security: [{ bearer: [] }] in the OpenAPI document. The published reference reflects this — search for the lock badge on any operation page in /api/*.

Issuing a key

[FOUNDER TO CONFIRM] — verify the exact dashboard path under Settings → Developers → API keys before launch.

Once you have the key, export it as TANQORY_API_KEY (every example in this guide assumes that name):

export TANQORY_API_KEY="your_key_here"

The header

Every authenticated request carries the same header pair:

Authorization: Bearer ${TANQORY_API_KEY}
Content-Type: application/json

Minimal curl:

curl https://api.tanqory.com/api/v1/stores \
  -H "Authorization: Bearer $TANQORY_API_KEY" \
  -H "Content-Type: application/json"

The full multi-language version is in Quickstart.

Operations that manage authentication

Authentication is not just one endpoint — it is a family of resources declared under the Authentication* and Auth - Social Accounts tags in the Admin API. Counts below are pulled from the spec and reflect publishable operations only:

Resource	Operations	Use it for
Authentication	18	Email + password login, session management, sign-out, token refresh.
Authentication - MFA	14	Enrol / verify / disable a second factor; recovery codes.
Auth - Social Accounts	5	Connect / disconnect Google / Apple / etc. identity providers.
Authentication - Account Management	4	Data export, account deletion, profile lifecycle.
Authentication - Email Change	4	Initiate + confirm primary email change.
Authentication - Phone	4	Verify / change / remove phone number.
Authentication - Secondary Email	4	Manage secondary email addresses.
Authentication - Avatar & Preferences	3	Upload avatar, edit user preferences.
Authentication - Profile	3	Read / update profile fields.
Authentication - Identity Confirmation	2	Re-confirm identity before sensitive operations.

Click into any resource to see the full operation list with method, path, request body, and response envelope.

Errors

The spec declares only a description line on 401 / 403; the structured envelope below is verified from the live gateway. See Errors for the full contract + code catalogue.

A missing or invalid token returns 401 with code auth_token_invalid:

{
  "error": {
    "type": "authentication_error",
    "code": "auth_token_invalid",
    "title": "Auth Token Invalid",
    "message": "Unauthorized",
    "status": 401,
    "doc_url": "https://docs.tanqory.com/errors/auth_token_invalid",
    "request_id": "…",
    "instance": "/api/v1/…"
  }
}

Status	Returned when (verified)	Action
401	Missing / invalid / expired token — code auth_token_invalid.	Re-issue the token; don't retry the same token.
403	Token is valid but the account is locked (spec: "Account locked").	Recognised but blocked — don't retry without user intervention.

Switch on error.code, not the status. Per-scope authorization rules are [FOUNDER TO CONFIRM] — the only 403 the spec declares today is the account-locked case.

Next steps

Topic	When to read it
Errors	After the first 401 in development.
Rate limits	Before adding retry logic — 401s are not retryable, 429s are.
Versioning	When you ship — pin a version so a future auth-flow change doesn't surprise you.
Trust Center	For SOC / privacy posture before procurement.