> ## 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.

# 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](/authentication), [Quickstart](/quickstart)) |
| **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](/introduction#environments) host (`https://staging-api.usetyms.com/v1/adam`). Email [developer@usetyms.com](mailto:developer@usetyms.com) for sandbox integration app credentials.
</Note>

## 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

<Steps>
  <Step title="Start authorization">
    Call [Get authorization URL](/api-reference/oauth/get-authorization-url) with `client_id`, `redirect_uri`, `reference`, `privacy_url`, and `terms_url`.
  </Step>

  <Step title="Redirect the user">
    Send the user to the `authorization_url` in the response. Tyms hosts sign-in and business selection at `https://app.usetyms.com/auth/oauth/self`.
  </Step>

  <Step title="Receive the authorization code">
    After consent, the user lands on your `redirect_uri` with `reference`, `authorization_code`, and `business_id` as query parameters.
  </Step>

  <Step title="Exchange for tokens">
    Call [Exchange authorization code](/api-reference/oauth/exchange-authorization-code) with your app `secret_key` and the code. Store `access_token`, `refresh_token`, `expires_at`, and `business_id`.
  </Step>

  <Step title="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).
  </Step>
</Steps>

`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:

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

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

Use [Validate OAuth session](/api-reference/oauth/validate-oauth-session) 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](/api-reference/oauth/refresh-access-token) 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](/api-reference/oauth/revoke-access) 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](/api-reference/overview) — errors, rate limits, response envelope
* [Authentication](/authentication) — 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.