Environments & API keys

Every request to Tokeflow is authenticated with an API key, and every key carries its own context: which environment it targets, whether it is safe to expose in a browser, and which entity it acts on behalf of. Understanding how that context is encoded lets you wire up integrations correctly the first time.

This page covers the base URL and versioning, how environments are represented, the four key forms, and the key lifecycle (create, rotate, revoke) you manage in the Tokeflow Dashboard.

Base URL and versioning

All API traffic goes to a single host, and every endpoint lives under a version prefix.

https://api.tokeflow.com/api/v1

Tokeflow uses URI versioning. The current version is v1, and it appears in the path of every endpoint:

curl https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxx"

There is no separate hostname for testing. The environment you operate in is a property of the key you send, not the URL. The same base URL serves every environment — Tokeflow resolves the environment from the key on each request.

How environments are encoded

Tokeflow keys are self-describing. Each key follows a fixed anatomy, and one of its segments names the environment the key is bound to:

{sk|pk}_{environment}_{org|mer}_{random}
   │          │            │         │
   │          │            │         └─ random, high-entropy secret
   │          │            └─ scope: organization (org) or merchant (mer)
   │          └─ environment the key is bound to
   └─ key type: sk = secret (server-side), pk = public (client-safe)

A live secret merchant key, for example, looks like this:

sk_live_mer_9f2c4a7b1e8d3c5a6b0f2e1d4c7a9b3e

Reading left to right:

Because the environment is baked into the key:

• Keys are not portable across environments. A key issued for one environment will not authenticate against another.
• You never switch hosts or versions to change environments — you switch keys.
• Each environment keeps its own isolated set of keys, data, and configuration. Activity performed with one environment's key never touches another's.

Secret vs. public keys

The first segment, sk or pk, is the single most important thing to get right.

• Secret keys (sk_…) authenticate server-to-server calls. They can perform privileged actions and must never appear in browser code, mobile apps, public repositories, logs, or anywhere a third party could read them.
• Public keys (pk_…) are restricted to a small set of client-safe scopes and are designed to be embedded in browser or client code. They cannot perform privileged server actions.

Server-side requests authenticate with the standard header:

Authorization: Bearer sk_live_mer_xxxxxxxx

Public keys are used by Tokeflow's client SDK rather than passed on the Authorization header directly. See the SDK overview for how pk_… keys are presented in browser contexts.

Organization vs. Merchant scope

The third segment, org or mer, determines which entity the key acts on behalf of. Tokeflow is multi-tenant: an Organization can contain many Merchants.

• A Merchant key is automatically scoped to its merchant. The merchant is inferred from the key, so you never pass a merchant_id.
• An Organization key spans every merchant in the org. For merchant-scoped resources, it must identify the target merchant explicitly — via the merchant_id query parameter on list/get requests, or the merchant_id body field on create requests.

# Organization key: target a specific merchant with merchant_id
curl "https://api.tokeflow.com/api/v1/transactions?merchant_id=mrc_a1b2c3" \
  -H "Authorization: Bearer sk_live_org_xxxxxxxx"

# Merchant key: merchant is inferred, no merchant_id needed
curl "https://api.tokeflow.com/api/v1/transactions" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxx"

Beyond entity scope, each key also carries permission scopes in resource:action form (for example transactions:read, products:write). A key can only perform actions its scopes allow. See Authentication for the full scope model.

The four key forms

Combining key type (sk/pk) with entity scope (org/mer) gives four distinct key forms. Choose the narrowest one that still does the job.

Key lifecycle

You create, rotate, and revoke keys in the Tokeflow Dashboard during onboarding and throughout the life of your integration. Keys are issued per environment and per entity.

Create a key

In the Dashboard, create a key by giving it:

• A human-readable name that identifies the integration (for example, Prod - Main Backend).
• A type (secret or public) and an entity scope (organization or merchant).
• The permission scopes it needs, in resource:action form. Grant only what the integration requires.

When the key is created, Tokeflow shows the full secret value exactly once. Copy it immediately into your secrets store — it cannot be retrieved again afterward. Only a short, non-sensitive prefix is shown in the Dashboard from that point on, so you can recognize the key without exposing it.

Use separate keys per integration

Issue a distinct key for each service, environment, and integration. Do not share one key across multiple systems.

Store secrets safely

Secret keys belong in a secrets manager or injected as environment variables at deploy time — never hardcoded in source, committed to version control, or embedded in client-side bundles.

// Read the key from the environment, never inline it
const apiKey = process.env.TOKEFLOW_SECRET_KEY;

const res = await fetch("https://api.tokeflow.com/api/v1/transactions", {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
});

Recommended practices:

• Keep secrets in a dedicated secrets manager and inject them at runtime.
• Add key files and .env files to .gitignore; scan commits for accidental leaks.
• Restrict who can read production secrets.
• Never log full key values. Log at most the non-sensitive prefix.

Rotate keys

Rotate keys on a regular schedule and whenever team members with access leave. Tokeflow supports overlapping rotation so you can roll keys with zero downtime:

1. Create a new key with the same scope and permissions in the Dashboard.
2. Deploy the new key to your service (via your secrets manager).
3. Verify the new key is serving live traffic.
4. Revoke the old key once it is no longer in use.

Because old and new keys are valid simultaneously during the overlap, there is no window where requests fail.

Rotate on exposure

If a secret key is ever exposed — committed to a repo, leaked in logs, shared outside your team, or sent to a client — treat it as compromised:

1. Create a replacement key immediately.
2. Deploy the replacement.
3. Revoke the exposed key right away.

Errors you may see

Authentication and authorization problems return the standard error envelope:

{
  "error": {
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid, revoked, or for a different environment.",
    "details": {},
    "request_id": "req_8f3c2a1b9d7e",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

If you see a 401 on a key you believe is valid, check that the environment segment of the key matches the environment you intend to call.

Next steps

• Authentication — headers, scopes, and worked auth examples.
• Introduction — how orchestration, routing, and multi-tenant governance fit together.
• SDK overview — using public keys safely in the browser.