NAV

Upbase API Docs

JavaScript

Introduction

Welcome to Upbase API! Upbase supports Next.JS. It also can be used on any web server-side framework in any language. Pure front-end application frameworks like Create-React-App should not be used as Upbase uses API keys and there is no way to secure API keys in these frameworks.

Demo

Live Demo, GitHub Repo, and Demo Video.

Setup

You must connect your Stripe account to Upbase.

Connect with

This will connect your Stripe account to the Upbase sandbox. The Upbase sandbox uses the Stripe test mode so you can build your application without processing real charges. When you are ready for production please email hello@upbase.com to get a Stripe production connect link emailed to you. For production the url is https://api.upbase.dev rather than https://api-dev.upbase.dev.

Once you are connected to Upbase via Stripe - you can get your Stripe Account ID from your dashboard (Settings > Accounts Settings > At the Top (e.g. acct_1234)).

Create Admin User

Once you have connected your Stripe Account to Upbase and have your Stripe Account ID you can create your admin user. Upbase suggests using Postman do the request as it is a one-time operation. The application_name field will show in Authy and Authy will try to automatically pull your company logo from the web.

HTTP Request

POST https://api-dev.upbase.dev/create_user

    {
        "stripe_account_id": "acct_1234",
        "application_name": "my_application_name"
    }

Response

The api_key field is the admin’s API key.

    {
        "user": {
            "username": "my_generated_username",
            "tenant": null,
            "scopes": ["example:example"],
            "api_key": "1234",
            "application_name": "my_application_name",
            "backup_codes": [
                "backup_code_1",
                "backup_code_2",
                "backup_code_3",
                "backup_code_4",
                "backup_code_5",
                "backup_code_6",
                "backup_code_7",
                "backup_code_8"
            ],
            "qr": "base64_encoded_string",
            "subscribed": false,
            "checkout_url": null
        }
    }

Get QR Code

You want to scan via Authy your QR code in case you misplace or want to regen your API key.

HTTP Request

GET https://api-dev.upbase.dev/get_qr

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

Response

A PNG (image) of the QR Code

Create Paying Users

Upbase currently only supports creating Stripe standard billing recurring payments without metering for stripe_price_id. Upbase only supports credit cards as a method of payment for subscriptions. You have to do the following two calls in ordered sequence.

Create Tenant

A tenant can be considered a team which have users. Stripe subscriptions are tied to tenants yet the JWT of the user will have the subscribed field either set to true or false based on the Stripe subscription status. A stripe_price_id is created by creating a product with a price in the Stripe dashboard. Stripe Tax is supported but it is an extra charge from Stripe and should only be included as a key if you have the service.

HTTP Request

POST https://api-dev.upbase.dev/create_tenant

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

    {
        "stripe_price_id": "price_1234",
        "success_url": "https://example.com/success",
        "cancel_url": "https://example.com/cancel",
        "stripe_tax": true,
    }

Response

The tenant field can be passed to the create_user endpoint.

{
    "tenant": "generated_tenant_name"
}

Create User

Users can have scopes that are published in the user’s JWT and can be used for authorization (like gating content). Scopes are optional (key can be omitted). The stripe_account_id is optional and can be used in a case where the billing is like from an agency app for creators to end-users. The creator would have to be connected via Stripe to Upbase as well. The field checkout_url is the Stripe Checkout URL that the user should be redirected to pay for their subscription. The QR is base64 encoded and can be decoded to an image (PNG).

HTTP Request

POST https://api-dev.upbase.dev/create_user

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

    {
        "application_name": "my_application_name",
        "stripe_account_id": "acct_1234",
        "tenant": "generated_tenant_name",
        "scopes": ["example:example"]
    }

Response

    {
        "user": {
            "username": "my_generated_username",
            "tenant": "generated_tenant_name",
            "scopes": ["example:example"],
            "api_key": "1234",
            "application_name": "my_application_name",
            "backup_codes": [
                "backup_code_1",
                "backup_code_2",
                "backup_code_3",
                "backup_code_4",
                "backup_code_5",
                "backup_code_6",
                "backup_code_7",
                "backup_code_8"
            ],
            "qr": "base64_encoded_string",
            "subscribed": false,
            "checkout_url": null
        }
    }

VOD Subscriptions

Upbase supports Bunny Stream and requires only that you add api-dev.upbase.dev and api.upbase.dev to the allowed domains in the security settings for the Bunny Stream library. This link should be your HLS video link in your app. It is also required to add your domain displaying the videos to the allowed domains in Bunny Stream.

Get Video

HTTP Request

GET https://api-dev.upbase.dev/get_video.m3u8

Required Query Params:

Example

https://api-dev.upbase.dev/get_video.m3u8?vid=1234&link=vz-4b2854f0-bc5.b-cdn.net&stripe_price_ids[]=price_1234&stripe_price_ids[]=price_5678&jwt=1234

Response

An HLS m3u8 playlist - it is recommened to use React Player to play the video.

Streaming Subscriptions

Upbase supports live streaming from Streamlabs OBS. The first step is to get a streaming key - the name of the server to connect to rtmp://rtmp.upbase.dev/live.

Go Live

It is recommended that every new live session you call this endpoint.

HTTP Request

POST https://api-dev.upbase.dev/go_live

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

Response

Use this Stream key and the server information rtmp://rtmp.upbase.dev/live in Streamlabs OBS in Preferences > Select Custom Streaming Service > enter the information.

{
    "key": "1234"
}

Get Live

HTTP Request

GET https://api-dev.upbase.dev/get_live.m3u8

Required Query Params:

Example

https://api-dev.upbase.dev/get_live.m3u8?stripe_price_ids[]=price_1234&stripe_price_ids[]=price_5678&jwt=1234&vid=1234

Response

An HLS m3u8 playlist - it is recommened to use React Player to play the video.

User Tips

Give Tip

Users when they are subscribed can give additional tips. The following example is for $55 USD you must add the two trailing zeros (for cents). Currently the tip currency is in USD (US Dollars) and cannot be changed. The return value is a Stripe Checkout URL that the user should be redirected. Some nations may charge tax on tips so you may need to pay for and enable Stripe Tax.

HTTP Request

POST https://api-dev.upbase.dev/give_tip

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

    {
        "amount": 5500,
        "success_url": "https://example.com/success",
        "cancel_url": "https://example.com/cancel",
        "stripe_tax": true,
    }

Response

{
    "url": "stripe_checkout_url"
}

Login Box

For the test environment it is login-dev while for production it is login for the request URL.

Login

HTTP Request

GET https://login-dev.upbase.com

Required Query Params:

Example

https://login-dev.upbase.com?image=https://file.com/image.png&redirect=https://google.com

Response

The redirect URL with the jwt appended to it.

https://google.com?jwt=1234

Search

To do searching - a user has to create a unique bucket then index into that bucket.

Create Bucket

HTTP Request

POST https://api-dev.upbase.dev/create_bucket

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

{
    "name": "bucket_1"
}

Response

200 if success

Index

HTTP Request

POST https://api-dev.upbase.dev/index

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

{
    "items": [{
        "collection": "coffee", 
        "bucket": "bucket_1", 
        "uuid": "49e28aae-88d4-4c19-86d8-51f2c9f11039", 
        "data": {
            "name": "roasted",
            "image": "https://img.com/bucket/123/123.jpg"
        },
        "locale": "eng",
        "indexes": ["name"]
    }]
}

locale is an optional field of an ISO 639-3 locale code - if not defined the locale will be auto-detected

Response

200 if success`

Search

HTTP Request

POST https://api-dev.upbase.dev/search

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

limit and offset are optional fields

{
    "collection": "coffee", 
    "bucket": "bucket_1", 
    "query": "roasted",
    "limit": 10,
    "offset": 10
}

Response

{
    "items": [{
        "collection": "coffee", 
        "bucket": "bucket_1", 
        "uuid": "49e28aae-88d4-4c19-86d8-51f2c9f11039", 
        "data": {
            "name": "roasted",
            "image": "https://img.com/bucket/123/123.jpg"
        },
        "locale": "eng",
        "indexes": ["name"]
    }]
}

Word Suggest

HTTP Request

POST https://api-dev.upbase.dev/suggest

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

limit is an optional field

{
    "collection": "coffee", 
    "bucket": "bucket_1", 
    "query": "r",
    "limit": 10
}

Response

{
    "suggestions": ["roasted"]
}

Deindex

HTTP Request

POST https://api-dev.upbase.dev/deindex

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

{
    "uuid": "49e28aae-88d4-4c19-86d8-51f2c9f11039"
}

Response

200 if success

Delete Collection

HTTP Request

POST https://api-dev.upbase.dev/delete_collection

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

{
    "collection": "coffee",
    "bucket": "bucket_1"
}

Response

200 if success

User Actions

Login

The backup_code field is optional and should only be used to use a backup_code. The totp field is the timed code in Authy.

HTTP Request

POST https://api-dev.upbase.dev/login

    {
        "username": "my_generated_username",
        "totp": "123456",
        "backup_code": "123456"
    }

Response

    {
        "jwt": "jwt_token",
        "api_key": "1234"
    }

Get User Info

HTTP Request

GET https://api-dev.upbase.dev/userinfo

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

Response

    {
        "user": {
            "username": "my_generated_username",
            "tenant": "my_tenant",
            "scopes": ["example:example"],
            "api_key": "123",
            "application_name": "my_application_name",
            "backup_codes": [
                "backup_code_1",
                "backup_code_2",
                "backup_code_3",
                "backup_code_4",
                "backup_code_5",
                "backup_code_6",
                "backup_code_7",
                "backup_code_8"
            ],
            "qr": "base64_encoded_string",
            "subscribed": false,
            "checkout_url": null
        }
    }

Subscribe Tenant

This is when a subscriber cancels their subscription and they need to renewed. After the successful call the user should be redirected to the url (stripe checkout url).

HTTP Request

POST https://api-dev.upbase.dev/subscribe_tenant

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

    {
        "stripe_price_id": "price_1234",
        "success_url": "https://example.com/success",
        "cancel_url": "https://example.com/cancel",
        "stripe_tax": true,
    }

Response

{
    "url": "stripe_checkout_url"
}

Regen Backup Codes

HTTP Request

GET https://api-dev.upbase.dev/regen_backup_codes

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

Response

200 if success

Regen API key

HTTP Request

GET https://api-dev.upbase.dev/regen_api_key

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

Response

200 if success

Manage Subscription

Upbase supports Stripe Customer Portal. Don’t forget to enable and setup the Customer Portal in Stripe Settings to your liking.

HTTP Request

POST https://api-dev.upbase.dev/manage_subscription

Put the user’s JWT or API key in this header Authorization Bearer: user_jwt_or_api_key

The return_url should be URL where the user manages their account in the application. (e.g. https://foods.com/users/123/edit)

{
    "return_url": "user_account_url"
}

Response

The response will be a Stripe Customer Portal URL that the user can be redirected to manage their subscription.

{
    "url": "stripe_customer_portal_url"
}

Get QR Code

HTTP Request

GET https://api-dev.upbase.dev/get_qr

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

Response

A PNG (image) of the QR Code

Admin Actions

Login

The backup_code field is optional and should only be used to use a backup_code. The totp field is the timed code in Authy.

HTTP Request

POST https://api-dev.upbase.dev/login

    {
        "username": "my_generated_username",
        "totp": "123456",
        "backup_code": "123456"
    }

Response

    {
        "jwt": "jwt_token",
        "api_key": "1234"
    }

Get User Info

HTTP Request

GET https://api-dev.upbase.dev/userinfo

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

Response

    {
        "user": {
            "username": "my_generated_username",
            "tenant": null,
            "scopes": ["example:example"],
            "api_key": "123",
            "application_name": "my_application_name",
            "backup_codes": [
                "backup_code_1",
                "backup_code_2",
                "backup_code_3",
                "backup_code_4",
                "backup_code_5",
                "backup_code_6",
                "backup_code_7",
                "backup_code_8"
            ],
            "qr": "base64_encoded_string",
            "subscribed": false,
            "checkout_url": null
        }
    }

Create Tenant

A tenant can be considered a team which have users. Stripe subscriptions are tied to tenants yet the JWT of the user will have the subscribed field either set to true or false based on the Stripe subscription status. A stripe_price_id is created by creating a product with a price in the Stripe dashboard. Stripe Tax is supported but it is an extra charge from Stripe and should only be included as a key if you have the service.

HTTP Request

POST https://api-dev.upbase.dev/create_tenant

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

    {
        "stripe_price_id": "price_1234",
        "success_url": "https://example.com/success",
        "cancel_url": "https://example.com/cancel",
        "stripe_tax": true,
    }

Response

{
    "tenant": "generated_tenant_name"
}

Create User

Users can have scopes that are published in the user’s JWT and can be used for authorization (like gating content). Scopes are optional (key can be omitted). The stripe_account_id is optional and can be used in a case where the billing is like from an agency app for creators to end-users. The creator would have to be connected via Stripe to Upbase as well.

HTTP Request

POST https://api-dev.upbase.dev/create_user

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

    {
        "application_name": "my_application_name",
        "stripe_account_id": "acct_1234",
        "tenant": "tenant_1",
        "scopes": ["example:example"]
    }

Response

The QR code is a base64 encoded and can be decoded to show a QR code PNG (image).

    {
        "user": {
            "username": "my_generated_username",
            "tenant": "tenant_1",
            "scopes": ["example:example"],
            "api_key": "123",
            "application_name": "my_application_name",
            "backup_codes": [
                "backup_code_1",
                "backup_code_2",
                "backup_code_3",
                "backup_code_4",
                "backup_code_5",
                "backup_code_6",
                "backup_code_7",
                "backup_code_8"
            ],
            "qr": "base64_encoded_string",
            "subscribed": false,
            "checkout_url": null
        }
    }

Delete User

This will delete user from Upbase.

HTTP Request

DEL https://api-dev.upbase.dev/delete_user

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

The username can be retrieved from the JWT in the sub field.

    {
        "username": "name_to_delete"
    }

Response

200 on success

Regen Backup Codes

HTTP Request

GET https://api-dev.upbase.dev/regen_backup_codes

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

Response

200 if success

Regen API key

HTTP Request

GET https://api-dev.upbase.dev/regen_api_key

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

Response

200 if success

Get QR Code

HTTP Request

GET https://api-dev.upbase.dev/get_qr

Put the admin’s JWT or API key in this header Authorization Bearer: admin_jwt_or_api_key

Response

A PNG (image) of the QR Code

JWT

Details

JWTs are valid for 24 hours. The subscribed will be true or false based on the Stripe status of the tenant that user belongs to subscription.

Format

{
  "exp": 1628731349,
  "iat": 1628644949,
  "iss": "https://api-dev.upbase.dev",
  "sub": "user-name",
  "aud": [
    "https://api-dev.upbase.dev/userinfo"
  ],
  "scopes": "example:example example2:example2"
}