This guide will help you integrate Beag's subscription management system into your application.
SaaS Client API Integration Guide
The SaaS Client API lets you access your clients' subscription details programmatically. Use it to verify subscription status and control feature access in your application.
=== Overview ===
How It Works
The SaaS Client API works as follows:
1. Your server makes an authenticated request to the API using your private API key
2. You can look up client subscription information by email or client ID
3. The API returns subscription details including status, plan, and dates
4. Your application uses this data to control access to features based on subscription status and plan
Base URL
All API endpoints are relative to:
<https://my-saas-basic-api-d5e3hpgdf0gnh2em.eastus-01.azurewebsites.net/api/v1/saas>
Authentication
All requests require an API key in the X-API-KEY header:
X-API-KEY: YOUR_SAAS_API_KEY
Important: Keep your API key confidential and only use it server-side.
=== API Endpoints ===
1. Get Client by Email
Use this endpoint to retrieve subscription details for a client by their email address:
GET <https://my-saas-basic-api-d5e3hpgdf0gnh2em.eastus-01.azurewebsites.net/api/v1/saas/clients/by-email/{email}>
# Headers
X-API-KEY: YOUR_SAAS_API_KEY (Required)
# Example Request:
curl -X GET "<https://my-saas-basic-api-d5e3hpgdf0gnh2em.eastus-01.azurewebsites.net/api/v1/saas/clients/by-email/user%40example.com>" \\
-H "X-API-KEY: YOUR_SAAS_API_KEY"
# Success Response (200 OK):
# Returns client subscription details
# Error Response (4xx):
# 401: Missing API key
# 403: Invalid API key
# 404: Client not found or no active subscription
2. Get Client by ID
Use this endpoint to retrieve subscription details for a client by their internal ID:
GET <https://my-saas-basic-api-d5e3hpgdf0gnh2em.eastus-01.azurewebsites.net/api/v1/saas/clients/by-id/{client_id}>
# Headers
X-API-KEY: YOUR_SAAS_API_KEY (Required)
# Example Request:
curl -X GET "<https://my-saas-basic-api-d5e3hpgdf0gnh2em.eastus-01.azurewebsites.net/api/v1/saas/clients/by-id/456>" \\
-H "X-API-KEY: YOUR_SAAS_API_KEY"
# Success Response (200 OK):
# Returns client subscription details
# Error Response (4xx):
# 401: Missing API key
# 403: Invalid API key
# 404: Client not found or no active subscription
Response Format
Success Response (200 OK):
{
"email": "[email protected]",
"status": "PAID",
"plan_id": 123,
"start_date": "2023-10-26T10:00:00Z",
"end_date": "2024-10-26T10:00:00Z",
"my_saas_app_id": "bgapp_56_2.WW-psLbJqXw",
"client_id": 456
}
Possible status values:
PAID: Subscription is active and paid
FAILED: Payment has failed
CANCELLED: Subscription has been cancelled
REFUNDED: Payment was refunded
PAUSED: Subscription is temporarily paused
RESUMED: Subscription was resumed after being paused
Error Codes:
Error Codes:
+-----------------------+---------------------------------------------------+
| Error Code | Description |
+-----------------------+---------------------------------------------------+
| client_not_found | Client with specified email/ID not found |
| subscription_not_found| No active subscription for this client |
| app_not_found | Application ID not found |
| api_key_invalid | The API key is invalid or inactive |
| app_inactive | SaaS application is inactive |
| server_error | An unexpected server error occurred |
+-----------------------+---------------------------------------------------+
=== Implementation ===
Server-Side Implementation
Here's an example of how to implement subscription checking in server-side JavaScript:
// Example: Checking if a user has an active subscription
async function checkUserSubscription(email) {
try {
// This code should run on your server, never on the client
const response = await fetch(
`https://my-saas-basic-api-d5e3hpgdf0gnh2em.eastus-01.azurewebsites.net/api/v1/saas/clients/by-email/${encodeURIComponent(email)}`,
{
method: 'GET',
headers: {
'X-API-KEY': 'YOUR_SAAS_API_KEY'
}
}
);
const data = await response.json();
if (response.ok) {
// User has an active subscription
console.log('Subscription status:', data.status);
console.log('Plan ID:', data.plan_id);
console.log('Subscription ends:', new Date(data.end_date).toLocaleDateString());
return data;
} else {
// Handle errors
console.error('Error:', data.code, data.message);
return null;
}
} catch (error) {
console.error('Failed to check subscription:', error);
return null;
}
}
Implementation Steps
1. Generate an API Key
Create an API key in your Beag dashboard under API settings.
2. Implement Server-Side Validation
Create endpoints in your backend to check subscription status.
3. Use Subscription Data
Control access to features based on subscription status and plan level.
Security Best Practices
Never call this API from client-side code. Your API key would be exposed.
Store your API key securely in environment variables
Implement proper error handling for all API responses
Consider caching subscription data briefly to reduce API calls
Type Conversion Issues
Note that the Beag API may return plan_id as an integer.
Add the Beag API key to your .env file:
# Other environment variables
BEAG_API_KEY=your_api_key_here
We use Beag as to process payment and membership in the system. So we need to create the worker that run every 1 hours to check the status of the users in the system whether they're active or not.
I want you to create the function to check the user status from Beag using User Email address and to get the plan_id, start_date, and end_date and update it in the User table in the database.
Keep the Beag API Key in the .env file.
Check the Beag API Instruction and Example here: @[Beag API NotePad]
The Beag API provides subscription information for clients: