Authentication

Introduction

SubsBase uses JWT as the main means to authenticate any operation (Query or Mutation). The token follows the standard JWT format and it is to be sent with any request in a Authorization header and preceded by the keywords Bearer.

Example

POST https://api.subsbase.io/core/graphql
Authorization: Bearer {your received jwt goes here}
All tokens are valid for 4 hours after which a new token needs to be requested.

Type of Tokens

There are 2 types of tokens that would be used to interact with the SubsBase Backend.

  1. Server Tokens
  2. Customer Tokens (your subscriber/customer)

Server Tokens

Server Tokens are to be used for backend-to-backend communication only. It assumes that it is coming from a trusted source and would be consumed by your backends.

The server token should not be leaked to the front-end as it gives full access to your SubsBase account

A server token is requested through the following Query to https://api.subsbase.io/auth. The server token could then be used to either Query or Mutate data directly or used to authenticate a customer for further processing.

query GetApiToken {
  getApiToken(siteId: "{your site id}", apiSecret: "{your api secret}") {
    isSuccess
    value
    message
  }
}
  • A true value in the isSuccess fields indicates a successful operation and the token would in the value field. Otherwise, the message would include more information about any error(s) that might have occurred
  • You can find your API secret in the Settings > Webhook and API Settings page on your Admin Portal.
  • {your site id} is the case-sensitive site id you want to use and which contains the plans you need to attach. Your SubsBase Admin Portal link is in the form of https://{your_siteId}.subsbase.io
The API Secret should be treated like a password, so it is not to be shared or hardcoded in your code-base repositories. Failure to keep the API secret private, could allow attackers or hijackers to push fraudulent information about your customers/subscribers to your backend services. If you feel the API secret has been comprised during the testing/development phases, you can easily regenerate a new secret in the Settings > Webhook and API Settings page on your Admin Portal.

Customer Tokens

Customer tokens are used to authenticate a specific customer. This is usually used when you want to allow a customer to manage their own subscription allowing them to access, edit, pause, or cancel their plans. The token is expected to be returned back to the browser with additional requests originating from the browser within a user's active session.

The Customer Token only allows action to be taken on that specific customer and doesn't allow access to plans, coupons, invoices or any other info that are not customer specific.

A server token is requested through the following Query to https://api.subsbase.io/auth/graphql.

Requesting a Customer Token requires that a server token is used to authenticate the request. The server token is expected in the Authorization header 
query GetCustomerToken {
  getCustomerToken(
    customerId: "{the customerId whom will proceed with the token}"
  ) {
    isSuccess
    value
    message
  }
}
  • A true value in the isSuccess fields indicates a successful operation and the token would in the value field. Otherwise, the message would include more information about any error(s) that might have occurred

Data flow

Table of Contents