Beag API Integration

Overview

This guide will help you integrate Beag’s subscription management system into your application.

Getting Started

Step 1: Login to Beag

1. Visit the Beag login page and sign in with your credentials.
2. If you don’t have an account, you’ll need to register first.

Step 2: Generate Your API Key

1. After logging in, go to My SaaS and select your SaaS application.
2. Navigate to the API Key Management section.
3. Click on Generate API Key.
4. Save this key in a secure location — it will only be shown once.
5. Copy the API documentation text and save it to a Notepad in Cursor.

Step 3: Configure Your Environment

Add the Beag API key to your .env file:

# Other environment variables
BEAG_API_KEY=your_api_key_here

Step 4: Insert this Prompt to Cursor

We use Beag to process payment and membership in the system. So we need to
create the worker that runs every 1 hour 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]

Beag API Details

The Beag API provides subscription information for clients.

• Base URL: https://my-saas-basic-api-d5e3hpgdf0gnh2em.eastus-01.azurewebsites.net/api/v1/saas
• Authentication: API key in X-API-KEY header
• Primary endpoint: GET /clients/by-email/{email}
• Secondary endpoint: GET /clients/by-id/{client_id}

API Endpoints

Get Client by Email

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"

Get Client by ID

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"

Response Format

A successful response contains:

{
  "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 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

Server-Side Implementation

Here’s an example of how to implement subscription checking in server-side JavaScript:

async function checkUserSubscription(email) {
  try {
    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": process.env.BEAG_API_KEY
        }
      }
    );

    const data = await response.json();

    if (response.ok) {
      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 {
      console.error("Error:", data.code, data.message);
      return null;
    }
  } catch (error) {
    console.error("Failed to check subscription:", error);
    return null;
  }
}

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.