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

​
Summary

There are two main steps to integrating Basic into your app: implement Basic Auth, then call the database APIs with the user’s access token.

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
Replace YOUR_CLIENT_ID, YOUR_REDIRECT_URI, and YOUR_STATE with your own values. scope must be a space-separated list (for example profile alone, or profile plus datastore scopes your app needs). The live contract matches the OpenAPI spec (GET /auth/authorize).
PKCE (recommended): You may include code_challenge and code_challenge_method=S256 on the authorize request and the matching code_verifier when exchanging the code at /auth/token. See Basic Auth for the full OAuth flow.
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"}'