First, check if there’s an existing Basic SDK for your technology stack and use it instead for a better dev experience!

​
Summary

There’s two main steps to integrating Basic into your app. You’ll need to implement Basic Auth, and then you’ll be able to access the database APIs.

Auth APIs guide

Implement signup / login flows for your app’s users

Database APIs guide

Write and display data safely in your app

​
Basic Auth APIs guide

Basic uses OAuth 2.0 for authentication. For more details, read about Basic Auth.

In this guide, you will:

  1. Use “redirect to sign in” endpoint to redirect users to account creation / login flow
  2. Extract code from URL
  3. Use “get auth token” endpoint with extracted code
  4. Store auth token object for future API calls
1

Use "redirect to sign in" endpoint

Create a button that redirects the user to the Basic Auth page, with the following required parameters (more info on required parameters):

  • client_id='YOUR_CLIENT_ID'
  • redirect_uri='YOUR_REDIRECT_URI'
  • response_type=code
  • scope=profile
  • state='YOUR_STATE'

Redirect URL template: https://api.basic.tech/auth/authorize?response_type=code&redirect_uri=YOUR_REDIRECT_URI&scope=profile&state=YOUR_STATE&client_id=YOUR_CLIENT_ID

Make sure to replace YOUR_CLIENT_ID, YOUR_REDIRECT_URI, YOUR_STATE with your own values

curl --request GET \
    --url 'https://api.basic.tech/auth/authorize?response_type=code&redirect_uri='YOUR_REDIRECT_URI'&scope=profile&state='YOUR_STATE'&client_id='YOUR_CLIENT_ID''
2

Extract code from URL

The authorization code will be in the URL as a code query parameter. For example: https://your-app.com/callback?code=1234567890.

You need to extract the code from the URL and use it in the next step.

# Assuming the URL is stored in a variable
URL="https://your-app.com/callback?code=1234567890"
CODE=$(echo $URL | grep -o 'code=[^&]*' | cut -d'=' -f2)
echo $CODE
3

Use "get auth token" endpoint with extracted code

Make a post request to /auth/token with the authorization code in the body. The response will be a JSON object with the access token and a refresh code.

Token URL template: https://api.basic.tech/auth/token

Make sure to replace YOUR_CODE with your own values

curl --request POST \
    --url 'https://api.basic.tech/auth/token' \
    --header 'Content-Type: application/json' \
    --data '{"code":"YOUR_CODE"}'
4

Store auth token object for future API calls

The response from the token endpoint will look like this:

{
  "access_token": "<string>",
  "token_type": "<string>",
  "expires_in": 123,
  "refresh_token": "<string>"
}

​
Basic database APIs guide

The database APIs are easy to use.

Make sure to check the validity of the access_token, and pass it in the Header of your API call.

If the access_token is expired, you’d repeat step 3 of the Auth APIs guide but using the refresh_token instead of the extracted code. This will return you a fresh new access_token.

Here’s how to validate and use the access token in different programming languages:

# Note: For bash, you'll need to use a JWT decoding tool like jq or jwt-cli
# Example using jwt-cli:
# if jwt decode YOUR_ACCESS_TOKEN | jq '.exp > now' | grep -q "true"; then
#   # Token is valid, proceed with API calls
curl --request GET \
 --url 'https://api.basic.tech/your-endpoint' \
 --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
# else
#   # Token is expired, refresh it
curl --request POST \
 --url 'https://api.basic.tech/auth/token' \
 --header 'Content-Type: application/json' \
 --data '{"refresh_token":"YOUR_REFRESH_TOKEN"}'