> ## 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** only for [Register business](/api-reference/register-business); OAuth is separate from that flow.

## 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-authorization) 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.useadam.io/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-access-token) 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.useadam.io/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-token-validate) 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-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-token) 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**