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

# OAuth 2.0

> Let Tyms users authorize your integration app to access their business data without sharing secret keys.

Use OAuth when you build an **integration app** (Zapier, Make, a marketplace connector, or your own product) and need **Tyms users** to grant **your app** access to **their** business — instead of asking them to paste a long-lived `tyms_sk_...` secret.

Tyms issues your app a **public key** (`tyms_pk_...`) and **secret key** (`tyms_sk_...`). End users sign in through the Tyms consent screen, pick a business, and your app receives short-lived tokens scoped to that connection.

## When to use OAuth vs a business key

| Approach | Best for |
| - | - |
| **Business `tyms_sk_...`** | Automating **your own** Tyms business ([Authentication](https://developer.tyms.io/authentication.md), [Quickstart](https://developer.tyms.io/quickstart.md)) |
| **OAuth** | Apps used by **many** Tyms customers, each connecting their own business |

Partner distributors still use a **partner key** for routes under **API reference** → **Partners**; OAuth is separate from that flow.

> [!NOTE]
>
> For pre-production testing, business-scoped API calls can use the [sandbox](https://developer.tyms.io/introduction.md#environments) host (`https://staging-api.tyms.io/v1/adam`). Email [developer@tyms.io](mailto:developer@tyms.io) for sandbox integration app credentials.

## Credentials

| Credential | Who holds it | Used for |
| - | - | - |
| `client_id` (`tyms_pk_...`) | Your integration app | Starting authorization; shown to users as your app identity |
| App `secret_key` (`tyms_sk_...`) | Your integration app (server-side only) | Exchanging codes, refreshing tokens, and authenticating API calls alongside the user's access token |
| `access_token` / `refresh_token` | Your integration app (per connected user) | Calling business-scoped endpoints on behalf of the user who authorized access |

Store the app **secret key** and all user tokens in a secret manager or secure server storage — never in client-side code or public repos.

## End-to-end flow

**1. Start authorization**

Call [Get authorization URL](https://developer.tyms.io/api-reference/oauth/get-authorization-url.md) with `client_id`, `redirect_uri`, `reference`, `privacy_url`, and `terms_url`.

**2. Redirect the user**

Send the user to the `authorization_url` in the response. Tyms hosts sign-in and business selection at `https://app.tyms.io/auth/oauth/self`.

**3. Receive the authorization code**

After consent, the user lands on your `redirect_uri` with `reference`, `authorization_code`, and `business_id` as query parameters.

**4. Exchange for tokens**

Call [Exchange authorization code](https://developer.tyms.io/api-reference/oauth/exchange-authorization-code.md) with your app `secret_key` and the code. Store `access_token`, `refresh_token`, `expires_at`, and `business_id`.

**5. Call business endpoints**

Send **both** your app `secret_key` and `Authorization: Bearer <access_token>` on every business-scoped request. See [Call with OAuth tokens](#call-business-endpoints-with-oauth).

`reference` is your correlation id for the connection attempt — generate a unique value per authorization and verify it matches on callback.

### Callback URL shape

```
https://yourapp.com/oauth/callback?reference=conn_abc123&authorization_code=AD...&business_id=...
```

Authorization codes expire in **10 minutes** and are **single-use**.

## Call business endpoints with OAuth

Every business-scoped request requires **both** credentials:

```bash cURL theme={null}
curl -sS -X GET "https://api.tyms.io/v1/adam/invoices" \
  -H "X-API-Key: tyms_sk_your_app_secret_key" \
  -H "Authorization: Bearer access_token_from_exchange"
```

The Bearer token selects **which authorized business** the call acts on. Your app `secret_key` identifies your integration to Tyms.

Use [Validate OAuth session](https://developer.tyms.io/api-reference/oauth/validate-oauth-session.md) to confirm a token and read business profile fields (including `authentication_method: "oauth"` and expiry).

## Token lifetime and refresh

* **Access tokens** expire after **60 minutes** (`expires_at` in the exchange response).
* Call [Refresh access token](https://developer.tyms.io/api-reference/oauth/refresh-access-token.md) with your app `secret_key`, `refresh_token`, and `business_id` to obtain a new access token without sending the user through consent again.
* Call [Revoke access](https://developer.tyms.io/api-reference/oauth/revoke-access.md) when a user disconnects your app. Provide `business_id` and either `access_token` or `refresh_token`.

## Subscription requirement

The connected business must have an **active Tyms subscription** eligible for Developer API access. Businesses without a qualifying subscription cannot complete authorization; API calls return **403** if subscription lapses after connect.

## Common errors

| Situation | HTTP | What to do |
| - | - | - |
| Invalid `client_id` | `400` | Check `tyms_pk_...` from Tyms |
| No businesses on the account | `400` | User must belong to at least one business |
| Business without active subscription | `403` | User must pick a subscribed business or upgrade |
| Expired or reused authorization code | `400` | Start a new authorization |
| Bearer token without app secret | `401` | Send `X-API-Key` with your app `secret_key` |
| Invalid or expired access token | `401` | Refresh or re-authorize |
| Subscription lapsed after connect | `403` | Prompt user to restore subscription or disconnect |
| User lost business access | `403` | Treat as revoked; remove stored tokens |

## Related reference

* [API overview](https://developer.tyms.io/api-reference/overview.md) — errors, rate limits, response envelope
* [Authentication](https://developer.tyms.io/authentication.md) — business and partner API keys (non-OAuth)
* OAuth endpoints under **API reference** → **OAuth**


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