> ## Documentation Index
> Fetch the complete documentation index at: https://developer.usetyms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Business API keys, partner keys, headers, and Developer API access requirements.

Most Tyms Developer API routes use a **business API key** in a header. You pass a secret, and the server enforces **which business** (or **partner program**) the credential belongs to.

Building an integration app for **many** Tyms customers? Use [OAuth 2.0](/oauth) instead of asking each user for their business secret key.

## Production vs sandbox

Credentials are **environment-specific**. Production keys from the Tyms app authenticate against `https://api.usetyms.com/v1/adam`; sandbox keys authenticate against `https://staging-api.usetyms.com/v1/adam`. See [Environments](/introduction#environments) for the full table.

To test integrations before production, email [developer@usetyms.com](mailto:developer@usetyms.com) for **sandbox account setup**. Tyms provisions staging businesses and issues keys that match the sandbox host.

## Two kinds of credentials

### Business secret key (`tyms_sk_...`)

Used for **every** `v1/adam` route **except** partner distributor routes and OAuth steps that document their own auth.

* Issued per business from the Tyms app (**Settings** → **Business settings** → **API**).
* Grants access **only** to that business’s data.
* Public key (`tyms_pk_...`) is not used as the Bearer-style secret for these REST calls; integrations use the **secret** key.

### Partner API key (`adam_partner_sk_...` or equivalent)

Used for **partner distributor** routes under **API reference** → **Partners** (full URLs under [Environments](/introduction#environments)):

* `POST /register-business`

* `GET /referred-businesses`

* `GET /referred-businesses/{business_uuid}/billing-status`

* `POST /referred-businesses/{business_uuid}/add-seats`

* `POST /referred-businesses/{business_uuid}/add-credits`

* Issued when Tyms onboards you as a **referral business partner** (distributor).

* Creates a **new** business and optionally returns that business’s Developer API keys when `grant_access` is `admin`.

* Seat and credit grants debit your **partner credit holding** (see [Partners](/partners-program)).

* After registration, use the returned **`tyms_sk_...`** for that customer’s day-to-day bookkeeping API calls — not the partner key.

<Note>
  Partner **program** onboarding (admin registration, contract terms, commission or prepaid structures) is handled outside this reference. If you are integrating as a partner, complete Tyms’s partner onboarding first so you receive partner credentials. Start with the [Partners guide](/partners-program) and **API reference** → **Partners**.
</Note>

## Accepted header names

Send the key in **any one** of these headers (same value):

* `X-API-Key`
* `api-key`
* `sk`

## Developer API subscription

On protected routes, the business must meet Tyms’s **Developer API subscription** rules. If not, the API responds with **403 Forbidden** and an explanatory `message`.

## Validate a business key

To confirm a key and load business metadata, call **`GET /auth/validate`**. Request/response fields are documented on [Validate business](/api-reference/authentication/validate-business).

## Security practices

* Store **`tyms_sk_...`** and partner secrets in a **secret manager** or environment variables — never in client-side code or public repos.
* Rotate keys from the Tyms app if a secret is exposed.
* Prefer **TLS** only (`https://api.usetyms.com` or `https://staging-api.usetyms.com` for sandbox).

## Related reference

* [OAuth 2.0](/oauth) — third-party integration apps connecting Tyms users
* [API overview](/api-reference/overview) — errors, rate limits, UUID rules
* [Partners](/partners-program) — onboarding, billing models, and distributor routes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.