Guides

Authentication

Every request to the Theyutes API is authenticated with a scoped bearer token. Mint as many as you need; lose them and revoke them in seconds.

Token format

A Theyutes API token looks like this:

tyk_K8c2vP9aLm3xQ4rT7sW1eN5oU0bH6yZ2fJ

The tyk_prefix is a fixed marker that lets secret scanners (GitHub, GitLab, AWS) catch it the moment it's pushed somewhere it shouldn't be. The 43 characters after the prefix are base64url-encoded random bytes. Tokens never expire on a clock — they live until you revoke them.

Sending the token

Pass the token in the Authorizationheader as a Bearer credential. We deliberately don't accept tokens in query strings — too easy to leak into server access logs and analytics tools.

http

Authorization: Bearer tyk_K8c2vP9aLm3xQ4rT7sW1eN5oU0bH6yZ2fJ

A live example using curl:

bash

curl 'https://theyutes.com/api/v1/orders' \
  -H 'Authorization: Bearer tyk_K8c2vP9aLm3xQ4rT7sW1eN5oU0bH6yZ2fJ'

One token, one integration

Mint a separate token per integration (ERP sync, IG mirror, internal dashboard, etc). When something breaks or leaks, you rotate one without taking the others down with it.

Scopes

Each token carries a set of scopes — the vocabulary that decides what it can read or change. Scopes follow <resource>:<access> where access is read or write. Write implies read, so a token with orders:write can also list and fetch orders without needing orders:read separately.

Resource	Scopes	What it grants
Orders	orders:read orders:write	Read order details, items, customer info. Write to advance status.
Products	products:read products:write	Read your catalogue. Write to create/update products and variants.
Customers	customers:read customers:write	Read customer profiles + lifetime stats. Write to update notes.
Refunds	refunds:read refunds:write	Read refund history. Write to issue refunds via Paystack.
Discounts	discounts:read discounts:write	Read codes + redemption stats. Write to create/edit discounts.
Inventory	inventory:read inventory:write	Read stock levels. Write to adjust stock (audit-logged).
Payouts	payouts:read	Read-only access to payouts + breakdowns.
Logistics	logistics:read logistics:write	Read shipment status + tracking. Write to quote and dispatch new shipments through the multi-carrier orchestrator.

Missing scopes return 403 insufficient_scope. See the errors guide for the full envelope shape.

IP allowlist

Optional, recommended for production tokens. When set, requests from any other IP are rejected before the token is even checked against the scope. Configure the allowlist on the token from Developers → API tokens → Edit.

Single IPs and CIDR ranges are both supported. A few realistic shapes:

text

# Single IP
203.0.113.42

# A /29 — your office's static block
198.51.100.16/29

# An entire /16 — only for closed-network corporate VPNs
10.0.0.0/16

Requests from outside the allowlist return 403 ip_blocked. If you're seeing this from a legitimate origin, double-check that the IP your server actually egresses from matches what your infra provider tells you — Lagos ISPs (and especially mobile carriers) NAT aggressively.

Rotation

We recommend rotating production tokens every 90 days. The pattern is overlap, not cutover:

Mint a new token with the same scopes.
Deploy your service with the new token. Keep the old one live.
When you've confirmed traffic on the new token (the Last used column in the tokens list updates within a minute), revoke the old one.

Revoked tokens fail immediately with 401 token_revoked — no grace period. If you accidentally revoke the wrong one, mint a replacement; we don't resurrect old tokens.

Storage best practices

Never commit a token to git. Even private repos. Use .env for local dev (and add it to .gitignore) and a secrets manager in production — Vercel, AWS Secrets Manager, Doppler, anywhere that's not your source tree.
Don't ship tokens to the browser. Every Theyutes endpoint is server-to-server. If you need browser code to take actions on behalf of a merchant, proxy through your own backend.
Log carefully.Tokens often leak through accidentally-verbose error reporting. If you're piping request headers anywhere, redact the Authorization line.
Audit usage. The audit log records every call by token, IP, and timestamp — a good place to spot anomalies.