This resource provides a guide on how to set up OAuth2.0 on Tyms.
Tyms supports OAuth 2.0 to help you securely authenticate and authorize users, whether you're working in sandbox mode for testing or operating a production application.
This guide walks you through the complete OAuth 2.0 flow so you can obtain access tokens and make API requests on behalf of your users.
✅ Why Use OAuth?
OAuth is essential when you want to:
- Access a user’s Tyms business data securely.
- Avoid handling user credentials directly.
- Create a seamless onboarding and authorization experience.
Once a user authorizes your application, you’ll receive an access token which should be included as a Bearer token in your API requests via the Authorization header.
🌐 OAuth 2.0 Endpoints
Below are the key endpoints for Tyms' OAuth flow. Replace {base_url} with the appropriate environment:
| Environment | Base URL |
|---|---|
| Sandbox | https://staging-api.tymsbook.com |
| Production | https://api.tyms.io |
| Purpose | Endpoint |
|---|---|
| User Authorization | {base_url}/api/v1/oauth/authorization |
| Access Token Retrieval | {base_url}/api/v1/oauth/access/token |
🔄 OAuth 2.0 Authorization Flow
The OAuth process involves four main steps:
- Redirect User to Tyms for Authorization
- User Approves Access to Their Tyms Account
- Tyms Redirects Back to Your App with an Authorization Code
- Exchange Authorization Code for an Access Token
🚀 Step-by-Step Guide
1. Initiate User Authorization
Redirect users to the Tyms OAuth authorization widget by sending a GET request to:
{base_url}/oauth/authorization
🔧 Required Query Parameters
| Parameter | Description |
|---|---|
reference | A unique reference for the user on your system |
client_id | Your Tyms public API key |
redirect_uri | The callback URL where Tyms should send the user back |
terms_url | URL to your terms and conditions |
privacy_url | URL to your privacy policy |
📌 Example URL
https://staging-api.tymsbook.com/oauth/authorization?reference=192303&client_id=tyms_pk_2a38835c-e3c6-47fc-80b3-123c4acdc1ee&redirect_uri=https://yourapp.com/callback&privacy_url=https://yourapp.com/privacy&terms_url=https://yourapp.com/terms
📥 Example Response
{
"status": "success",
"message": "Authorization request initiated successfully",
"data": "https://tymsbook-web.web.app/auth/oauth?client_id=tyms_pk_2a38835c-e3c6-47fc-80b3-123c4acdc1ee&redirect_uri=https://yourapp.com/callback&reference=192303&privacy_url=https://yourapp.com/privacy&terms_url=https://yourapp.com/terms"
}
✅ Redirect the user to the URL in the data field. Tyms will handle the authorization interface.
2. Tyms Prompts for Authorization
The user is asked to authorize your app to access their Tyms business. If they approve, Tyms redirects them back to your specified redirect_uri with the following query parameters:
| Parameter | Description |
|---|---|
reference | The original user reference you sent |
authorization_code | Temporary code used to get the access token (expires in 10 minutes) |
business_id | ID of the authorized business on Tyms |
📥 Example Redirect URL
https://yourapp.com/callback?reference=192303&authorization_code=AUTH_CODE&business_id=a123
3. Exchange Authorization Code for Access Token
Once you receive the authorization_code, exchange it for an access token by sending a POST request to:
{base_url}/api/v1/oauth/access/token
🔧 Required Body Parameters
| Parameter | Description |
|---|---|
authorization_code | The code received from the redirect |
client_id | Your public API key |
client_secret | Your secret API key |
📥 Example Request
{
"authorization_code": "AUTH_CODE",
"client_id": "tyms_pk_2a38835c-e3c6-47fc-80b3-123c4acdc1ee",
"client_secret": "tyms_sk_0e3c6-47fc-80b3-9837c123c4acdc1ee"
}
📤 Example Response
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
"expires_in": 86400,
"business_id": "a123"
}
4. Make Authenticated API Calls
Use the access token in the Authorization header of your requests:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...
📘 Notes
- Access tokens are valid for 24 hours (
86400seconds). - Tokens should be stored securely and refreshed when expired (token refresh coming soon).
- OAuth is required for multi-tenant platforms, B2B apps, and any system where users need to manage their own Tyms data within your platform.