Authentication

Overview

The Smartbills API uses JWT Bearer token authentication. Every API request must include a valid token in the Authorization header. Tokens can be obtained through API keys or OAuth2 flows.

Before you begin: You need a Smartbills account and API keys to authenticate. Visit developers.smartbills.io to get started.

Authentication Header

Include your token in the Authorization header of every request:

GET /v1/expenses HTTP/1.1
Host: api.smartbills.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
x-tenant-id: 123

The header format is:

Authorization: Bearer {token}

Where {token} is either:

An API key (e.g., sk_live_1234567890abcdef)
An OAuth2 access token obtained through the token endpoint

Multi-Tenant Header

Smartbills is a multi-tenant platform. You must include the x-tenant-id header to specify the business context:

x-tenant-id: 123

This header tells the API which business’s data you want to access. Your token must have permission to access the specified business.

Locale Header

Use the Accept-Language header to receive localized responses:

Accept-Language: en-CA

Supported locales: en-CA, fr-CA, en-US. See Localizations for details.

Complete Request Headers

A complete authenticated request includes these headers:

GET /v1/expenses HTTP/1.1
Host: api.smartbills.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
x-tenant-id: 123
Accept-Language: en-CA

OAuth2 Authentication

Client Credentials Flow

Use this flow for server-to-server communication where no user interaction is required. Endpoint: POST https://api.smartbills.io/auth/connect/token Request:

POST /auth/connect/token HTTP/1.1
Host: api.smartbills.io
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Code Examples

curl --request POST \
  --url https://api.smartbills.io/auth/connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET'

import { SmartbillsClient } from '@smartbills/sdk';

const client = new SmartbillsClient({
  accessToken: 'YOUR_API_KEY',
  businessId: 123
});

// The SDK handles token management automatically.
// For manual OAuth2 flows:
const tokenResponse = await fetch('https://api.smartbills.io/auth/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET'
  })
});

const { access_token, expires_in } = await tokenResponse.json();

from smartbills import SmartbillsClient
import requests

client = SmartbillsClient(access_token="YOUR_API_KEY", business_id=123)

# The SDK handles token management automatically.
# For manual OAuth2 flows:
token_response = requests.post(
    'https://api.smartbills.io/auth/connect/token',
    data={
        'grant_type': 'client_credentials',
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET'
    }
)

token_data = token_response.json()
access_token = token_data['access_token']
expires_in = token_data['expires_in']

Authorization Code Flow

Use this flow for user-facing applications where you need to act on behalf of a user. Step 1: Redirect to Authorization Endpoint

GET /auth/connect/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=expenses.read expenses.write
Host: api.smartbills.io

Step 2: Exchange Authorization Code for Access Token

POST /auth/connect/token HTTP/1.1
Host: api.smartbills.io
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_abcdef123456..."
}

Code Examples

# Step 2: Exchange authorization code for token
curl --request POST \
  --url https://api.smartbills.io/auth/connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'code=AUTHORIZATION_CODE' \
  --data 'redirect_uri=YOUR_REDIRECT_URI' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET'

// Step 1: Redirect user to authorization page
const authUrl = new URL('https://api.smartbills.io/auth/connect/authorize');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('client_id', 'YOUR_CLIENT_ID');
authUrl.searchParams.set('redirect_uri', 'YOUR_REDIRECT_URI');
authUrl.searchParams.set('scope', 'expenses.read expenses.write');
// Redirect: window.location.href = authUrl.toString();

// Step 2: Exchange code for token (in your callback handler)
const tokenResponse = await fetch('https://api.smartbills.io/auth/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: 'AUTHORIZATION_CODE',
    redirect_uri: 'YOUR_REDIRECT_URI',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET'
  })
});

const { access_token, refresh_token, expires_in } = await tokenResponse.json();

import requests
from urllib.parse import urlencode

# Step 1: Build authorization URL
auth_params = {
    'response_type': 'code',
    'client_id': 'YOUR_CLIENT_ID',
    'redirect_uri': 'YOUR_REDIRECT_URI',
    'scope': 'expenses.read expenses.write'
}
auth_url = f"https://api.smartbills.io/auth/connect/authorize?{urlencode(auth_params)}"
# Redirect user to auth_url

# Step 2: Exchange code for token (in your callback handler)
token_response = requests.post(
    'https://api.smartbills.io/auth/connect/token',
    data={
        'grant_type': 'authorization_code',
        'code': 'AUTHORIZATION_CODE',
        'redirect_uri': 'YOUR_REDIRECT_URI',
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET'
    }
)

token_data = token_response.json()
access_token = token_data['access_token']
refresh_token = token_data['refresh_token']

Token Expiration and Refresh

Access tokens expire after a set period (typically 3600 seconds / 1 hour). Use the expires_in field to know when a token will expire.

Refreshing Tokens

When your access token expires, use the refresh token to obtain a new one without requiring user interaction:

curl --request POST \
  --url https://api.smartbills.io/auth/connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'refresh_token=YOUR_REFRESH_TOKEN' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET'

async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://api.smartbills.io/auth/connect/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET'
    })
  });

  const { access_token, refresh_token, expires_in } = await response.json();

  // Store the new tokens securely
  return { access_token, refresh_token, expires_in };
}

def refresh_access_token(refresh_token):
    response = requests.post(
        'https://api.smartbills.io/auth/connect/token',
        data={
            'grant_type': 'refresh_token',
            'refresh_token': refresh_token,
            'client_id': 'YOUR_CLIENT_ID',
            'client_secret': 'YOUR_CLIENT_SECRET'
        }
    )

    token_data = response.json()
    # Store the new tokens securely
    return token_data

Refresh Token Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_newrefreshtoken..."
}

Refresh token rotation: Each time you use a refresh token, a new refresh token is returned. The old refresh token is invalidated. Always store the latest refresh token.

Using the SDKs

The official SDKs handle authentication, token refresh, and header management automatically:

import { SmartbillsClient } from '@smartbills/sdk';

const client = new SmartbillsClient({
  accessToken: 'YOUR_API_KEY',
  businessId: 123
});

// The SDK automatically includes Authorization and x-tenant-id headers
const expenses = await client.expenses.list();

from smartbills import SmartbillsClient

client = SmartbillsClient(access_token="YOUR_API_KEY", business_id=123)

# The SDK automatically includes Authorization and x-tenant-id headers
expenses = client.expenses.list()

Authentication Errors

HTTP Status	Error Code	Description
401	`UNAUTHORIZED`	Missing or invalid API key
401	`API_KEY_EXPIRED`	API key has expired
401	`API_KEY_REVOKED`	API key has been revoked
401	`INVALID_TOKEN`	Invalid or malformed JWT token
403	`FORBIDDEN`	Token does not have required permissions
403	`BUSINESS_ACCESS_DENIED`	No access to the specified business

Example Error Response

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "requestId": "req_1234567890abcdef"
  }
}

Security Best Practices

Protect Your Credentials

Store API keys and secrets in environment variables
Never commit credentials to version control
Never expose tokens in client-side code
Use HTTPS for all API requests

Use Appropriate Scopes

Request only the scopes your application needs
Use read-only scopes when you do not need write access
Review and audit scopes regularly

Handle Token Expiration

Check the expires_in value after obtaining tokens
Implement automatic token refresh before expiration
Handle 401 errors by refreshing and retrying

Rotate Keys Regularly

Rotate API keys every 90 days
Revoke compromised keys immediately
Use separate keys for each environment

API Keys

Create and manage API keys

Environments

Sandbox and production environments

Error Handling

Handle authentication errors

Rate Limits

Understand rate limiting

Getting Started

Core Concepts

Expenses

Business Expenses

Expense Reports

Mileage

Approvals

Bills & Accounts Payable

Vendors

Vault

Team & Administration

Settings

Mobile App

Overview

Authentication Header

Multi-Tenant Header

Locale Header

Complete Request Headers

OAuth2 Authentication

Client Credentials Flow

Code Examples

Authorization Code Flow

Code Examples

Token Expiration and Refresh

Refreshing Tokens

Using the SDKs

Authentication Errors

Example Error Response

Security Best Practices

API Keys

Environments

Error Handling

Rate Limits

​Overview

​Authentication Header

​Multi-Tenant Header

​Locale Header

​Complete Request Headers

​OAuth2 Authentication

​Client Credentials Flow

​Code Examples

​Authorization Code Flow

​Code Examples

​Token Expiration and Refresh

​Refreshing Tokens

​Using the SDKs

​Authentication Errors

​Example Error Response

​Security Best Practices

​Related Resources

API Keys

Environments

Error Handling

Rate Limits

Overview

Authentication Header

Multi-Tenant Header

Locale Header

Complete Request Headers

OAuth2 Authentication

Client Credentials Flow

Code Examples

Authorization Code Flow

Code Examples

Token Expiration and Refresh

Refreshing Tokens

Using the SDKs

Authentication Errors

Example Error Response

Security Best Practices

Related Resources