SaaSquatch Help Center

The Open Endpoints in the are designed for simplified use of the SaaSquatch REST API functionality in client applications like the Mobile widget and SDK.

Use Cases

The primary use case for the Open Endpoints is in client-server interactions like the Mobile Widget and Mobile SDK. These actions typically involve looking up information about a referred user or who referred them.

Some examples include:

Enable Open Endpoints

Open Endpoints are disabled by default for security and functionality reasons. As a core component of our Mobile SDK, Open Endpoints are provided as an optional addon to Pro and Enterprise plans. If the Mobile SDK, and Open Endpoints, are features you would like to make use of, please contact our sales team to discuss adding them to your subsciption.

Authentication Options

The Open Enpoints provide flexible authentication options:

  • Authenticated - For Open Endpoint calls that reqire authentication there are two options:
    • JWT - JWTs can be used for requests that require authentication.
    • API Key - Your tenant's API key can also be used for requests that require authentication.
  • Unauthenticated - Some Open Endpoints do not require any form of authentication.

Rate Limit

For security purposes there are limits on the number of requests that can be made using unauthenticated, and JWT authenticated, requests on your live tenant. Requests made using your API key, and any request made on your Test tenant, are not rate limited.

This functionallity is desiged such that only your backend system (as part of server-server communcation authenticated with your API key) can make a large number of requests. Individual client devices are only able to make a limited number of requests.

If the Open Endpoints are used correctly (mainly that server-server authentication is being done with your API key) these limitations should never be encountered.

The following table summarizes the Open Endpoint methods that are available for use, their required authentication, and the rate limits that apply when using unauthenitcated calls or those authenticated with JWTs:

Open Endpoint method Authentication required Rate limits
Create a user Requires Write Token or API key Limited to 50 per day per IP
Lookup a user Requires Read Token or API key Limited to 100 per hour per IP
Lookup a user by referral code No authentication required. Limited to 100 per hour per IP
Lookup a referral code No authentication required. Limited to 100 per hour per IP
Apply a referral code Requires Write Token or API key. Limited to 100 per hour per IP
List referrals Requires Read Token or API key. Limited to 100 per hour per IP

Authentication with JWT

Authentication with JWTs should be used in client-server use cases.

The Referral SaaSquatch API accepts two types of JWTs: read tokens, and write tokens. The read tokens are used for calls that involve looking up data while write tokens are used when adding or editing information.

The format of the JWT payloads required for read and write tokens are outlined below:

Read Token Payload Write Token Payload
The payload of a read token is based on the user id and account id:
{
  "user": {
      "id": "adfgafdg",
      "accountId": "adfklajdnrerereACdsedf"
    },
    "exp": 1462327764 //optional date in seconds since the epoch
}
The payload of a write token contains the complete user object:
{
  "user": {
      "id": "adfgafdg",
      "accountId": "adfklajdnrerereACdsedf",
      "email": "bob@example.com",
      "firstName": "Bob",
      "lastName": "Testerson", //optional
      "locale": "en_US", //optional
      "referralCode": "BOBTESTERSON", //optional
      "imageUrl": "" //optional
    },
    "exp": 1462327764 //optional date in seconds since the epoch
}

Note: Do not include paymentProviderId in the Write Token Payload you are trying to sign.

Building the JWT

The process for building the JWT is outlined on our JSON Web Tokens page.

Make sure you that you are trying to sign the correct format of the payload (Read Token vs Write Token) for your specific Open Endpoint API call.

Authentication with API Key

Authenticaion with your API key should be done when conducting server-server communication.

Authenticating Open Endpoint calls with an API key is done in the same way as with our standard API calls, details for which can be found in API Authentication.