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

Partner distributors still use a partner key for routes under API reference → Partners; OAuth is separate from that flow.
For pre-production testing, business-scoped API calls can use the sandbox host (https://staging-api.usetyms.com/v1/adam). Email developer@usetyms.com for sandbox integration app credentials.

​
Credentials

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.usetyms.com/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

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

​
Call business endpoints with OAuth

Every business-scoped request requires both credentials:
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

  • API overview — errors, rate limits, response envelope
  • Authentication — business and partner API keys (non-OAuth)
  • OAuth endpoints under API reference → OAuth