Skip to main content
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

ApproachBest for
Business tyms_sk_...Automating your own Tyms business (Authentication, Quickstart)
OAuthApps used by many Tyms customers, each connecting their own business
Partner distributors still use a partner key only for Register business; OAuth is separate from that flow.

​
Credentials

CredentialWho holds itUsed for
client_id (tyms_pk_...)Your integration appStarting 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_tokenYour 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 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.useadam.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 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.
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: 
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"
The Bearer token selects which authorized business the call acts on. Your app secret_key identifies your integration to Tyms. Use 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 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 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

SituationHTTPWhat to do
Invalid client_id400Check tyms_pk_... from Tyms
No businesses on the account400User must belong to at least one business
Business without active subscription403User must pick a subscribed business or upgrade
Expired or reused authorization code400Start a new authorization
Bearer token without app secret401Send X-API-Key with your app secret_key
Invalid or expired access token401Refresh or re-authorize
Subscription lapsed after connect403Prompt user to restore subscription or disconnect
User lost business access403Treat as revoked; remove stored tokens
  • API overview — errors, rate limits, response envelope
  • Authentication — business and partner API keys (non-OAuth)
  • OAuth endpoints under API reference → OAuth