JWT Authentication

JWT (JSON Web Token) authentication uses long-lived refresh tokens and short-lived access tokens. This method is ideal for user-based access and trial evaluation.

Token Lifecycle

Refresh Token

• Lifetime: 30 days (for trial), longer for production tokens
• Purpose: Generates new access tokens
• Usage: Store securely and use to refresh access tokens periodically

Access Token

• Lifetime: 1 hour
• Purpose: Used to authenticate API requests
• Usage: Include in request headers; generate new one when expired

Getting Your JWT Refresh Token

Request a Trial Token

For trial access, request a free JWT token from the Get an API access page.

Trial tokens are limited in functionality and expiration. See Free Trial for limitations.

Production Tokens

Get refresh tokens from Vainu UI: https://vainu.app/settings/api-access

Using JWT Tokens

Step 1: Get an Access Token

Make a POST request to the token refresh endpoint with your refresh token:

import requests

REFRESH_TOKEN = "your_refresh_token_here"
TOKEN_ENDPOINT = "https://api.vainu.io/api/token_authentication/refresh/"

payload = {
    "refresh": REFRESH_TOKEN
}

response = requests.post(TOKEN_ENDPOINT, json=payload)
token_response = response.json()
access_token = token_response["access"]

Step 2: Make API Requests

Use the access token in your API requests:

import requests

BASE_URL = "https://api.vainu.io/api/v3"
ENDPOINT = f"{BASE_URL}/organizations/"
ACCESS_TOKEN = access_token  # From step 1

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json"
}

payload = {
    "query": {"?ALL": []},
    "database": "FI",
    "fields": ["business_id", "name"],
    "limit": 10
}

response = requests.post(ENDPOINT, headers=headers, json=payload)
data = response.json()

Step 3: Refresh When Expired

When your access token expires refresh it using the refresh token:

# Refresh token if expired
response = requests.post(TOKEN_ENDPOINT, json={"refresh": REFRESH_TOKEN})
new_access_token = response.json()["access"]

Error Handling

Common JWT-related errors: