API Keys

Overview

API keys are the primary method of authenticating with the Smartbills API. Each key is tied to your user account and inherits your permissions. This guide covers everything you need to know about creating, using, and managing API keys securely.

API keys are powerful: They provide full access to your account via the API. Treat them like passwords and never share them publicly.

Creating API Keys

Generate Your First API Key

Navigate to API Keys

Log in to app.smartbills.io
Click your profile icon (top right)
Select Settings
Navigate to Developer > API Keys

Create New Key

Click Create New API Key
Enter a descriptive name for the key (e.g., “Production Server”, “Development Environment”)
(Optional) Set an expiration date
(Optional) Restrict to specific IP addresses
Click Generate Key

Copy Your Key

Your API key will be displayed once
Copy it immediately to a secure location
Store it in your password manager or environment variables
Click I’ve saved my key to confirm

Important: API keys are only shown once at creation. If you lose a key, you must revoke it and create a new one.

API Key Types

Smartbills provides two types of API keys for different environments:

Test Keys

sk_test_1234567890abcdef...

Use for:

Development and testing
Staging environments
Integration testing
Learning the API

Characteristics:

Prefix: sk_test_
Operates on separate test data
Higher rate limits for testing
No real charges or transactions
Safe to share with your development team

Test keys are perfect for development. They work with all endpoints but operate on separate test data that does not affect production.

Live Keys

sk_live_1234567890abcdef...

Use for:

Production environments
Live applications
Real expense processing
Production integrations

Characteristics:

Prefix: sk_live_
Real production data
Standard rate limits
Processes real expenses
Must be kept highly secure

Security: Never commit live keys to version control or expose them in client-side code.

Using API Keys

Authentication Header

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Complete Example

curl --request GET \
  --url https://api.smartbills.io/v1/expenses \
  --header 'Authorization: Bearer sk_live_1234567890abcdef' \
  --header 'Content-Type: application/json' \
  --header 'x-tenant-id: 123'

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

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

const expenses = await client.expenses.list();

from smartbills import SmartbillsClient

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

expenses = client.expenses.list()

Key Permissions and Scopes

Permission Inheritance

API keys inherit the permissions of the user who created them. If you have access to multiple businesses, your key will work with all of them via the x-tenant-id header.

Available Scopes

Scopes follow a resource.action format. The complete, authoritative list is published at /auth/.well-known/openid-configuration under scopes_supported.

Business Scopes

businesses.read - View business information, list businesses, get business detailsbusinesses.write - Create new businesses, update business information, modify settings

Expense Scopes

expenses.read - List expenses, get expense details, download attachments, export dataexpenses.write - Upload expenses, update expense information, add or remove attachments, categorize expensesreceipts.read / receipts.write - Access and modify the underlying receipts

Expense Report Scopes

expense-reports.read - List reports, get report details, view report timelineexpense-reports.write - Create reports, update report details, add or remove expensesexpense-reports.submit - Submit reports for approvalexpense-reports.approve / expense-reports.reject - Act on reports awaiting your approvalexpense-reports.reimburse - Mark reports as reimbursed

Accounts Payable Scopes

bills.read / bills.write - Access and modify billsvendors.read / vendors.write - Access and modify vendors

Identity Scopes

openid - Required for any OpenID Connect flowprofile, email, phone, address, full_name - Claims about the signed-in useroffline_access - Issue a refresh token alongside the access token

Platform Scopes

webhooks.read / webhooks.write - Manage webhook endpointsdevelopers.read / developers.write - Manage developer settingsnotifications.read / notifications.write - Access and manage notifications

Managing API Keys

View All Keys

See all your API keys in the dashboard:

Navigate to Settings > Developer > API Keys
View list of all active keys with:
- Key name
- Key prefix (first/last 4 characters)
- Creation date
- Last used timestamp
- Expiration date (if set)

Revoking Keys

Immediately disable an API key:

Navigate to your API keys list
Find the key to revoke
Click Revoke or the trash icon
Confirm the action

Immediate effect: Revoking a key immediately stops all requests using that key. Ensure you have a replacement key in place first.

When to revoke:

Key has been compromised or exposed
Employee with access has left the organization
Migrating to a new key
No longer using an integration
Suspected unauthorized use

Rotating Keys

Best practice: rotate keys regularly.

Create New Key

Generate a new API key with the same permissions.

Update Your Application

Replace the old key with the new one in your application. Test thoroughly.

Monitor

Watch for any requests still using the old key. Check the “Last Used” timestamp.

Revoke Old Key

Once confident the new key is working, revoke the old one.

Rotation schedule: Rotate API keys every 90 days for production environments, or whenever team members with access change.

Security Best Practices

Store in Environment Variables

# .env file (never commit this!)
SMARTBILLS_API_KEY=sk_live_1234567890abcdef
SMARTBILLS_BUSINESS_ID=123

// Use in your code
const apiKey = process.env.SMARTBILLS_API_KEY;

import os
api_key = os.environ.get('SMARTBILLS_API_KEY')

Use Different Keys per Environment

Development: test key (sk_test_...)
Staging: separate test key
Production: live key (sk_live_...)

Never use the same key across environments.

What to Avoid

Never do these:

Commit API keys to version control (Git, SVN, etc.)
Expose keys in client-side code (JavaScript bundles, mobile apps)
Share keys in emails, Slack, or other messaging platforms
Hardcode keys in source code
Use production keys in development
Store keys in unencrypted files
Include keys in URLs or query parameters
Log API keys in application logs

If a Key Is Exposed

Revoke Immediately

Go to Settings > API Keys and revoke the exposed key right away.

Generate New Key

Create a replacement key immediately.

Update Your Application

Replace the exposed key in your application.

Review Usage

Check the “Last Used” timestamp and recent activity for suspicious requests.

Contact Support

If you suspect unauthorized use, contact [email protected].

Troubleshooting

401 Unauthorized Error

Possible causes:

Missing Authorization header - Include Authorization: Bearer YOUR_API_KEY
Incorrect format - Ensure “Bearer ” prefix is included with no extra spaces
Revoked or expired key - Check if the key is still active in the dashboard
Wrong key type - Use sk_live_ for production and sk_test_ for sandbox

403 Forbidden Error

Possible causes:

Insufficient permissions - Your user account lacks necessary permissions
IP restriction - Request from an unauthorized IP address
Business access - Trying to access a business you are not a member of

Cannot Create API Key

Possible causes:

Reached key limit - Free plan: 2 keys max, Professional: 10 keys max, Enterprise: Unlimited
Insufficient permissions - Only account owners and admins can create API keys

Authentication

Complete authentication documentation

Environments

Sandbox and production environments

Rate Limits

Understand API rate limiting

Error Handling

Handle API errors effectively

Getting Started

Core Concepts

Expenses

Business Expenses

Expense Reports

Mileage

Approvals

Bills & Accounts Payable

Vendors

Vault

Team & Administration

Settings

Mobile App

Overview

Creating API Keys

Generate Your First API Key

API Key Types

Test Keys

Live Keys

Using API Keys

Authentication Header

Complete Example

Key Permissions and Scopes

Permission Inheritance

Available Scopes

Managing API Keys

View All Keys

Revoking Keys

Rotating Keys

Security Best Practices

Store in Environment Variables

Use Different Keys per Environment

What to Avoid

If a Key Is Exposed

Troubleshooting

Authentication

Environments

Rate Limits

Error Handling

​Overview

​Creating API Keys

​Generate Your First API Key

​API Key Types

​Test Keys

​Live Keys

​Using API Keys

​Authentication Header

​Complete Example

​Key Permissions and Scopes

​Permission Inheritance

​Available Scopes

​Managing API Keys

​View All Keys

​Revoking Keys

​Rotating Keys

​Security Best Practices

​Store in Environment Variables

​Use Different Keys per Environment

​What to Avoid

​If a Key Is Exposed

​Troubleshooting

​Related Resources

Authentication

Environments

Rate Limits

Error Handling

Overview

Creating API Keys

Generate Your First API Key

API Key Types

Test Keys

Live Keys

Using API Keys

Authentication Header

Complete Example

Key Permissions and Scopes

Permission Inheritance

Available Scopes

Managing API Keys

View All Keys

Revoking Keys

Rotating Keys

Security Best Practices

Store in Environment Variables

Use Different Keys per Environment

What to Avoid

If a Key Is Exposed

Troubleshooting

Related Resources