API Keys - Smartbills

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
- Example: “Production Server”
- Example: “Development Environment”
- Example: “Mobile App Integration”
(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 delete 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_
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.

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/user \
  --header 'Authorization: Bearer sk_live_1234567890abcdef' \
  --header 'Content-Type: application/json'

const apiKey = process.env.SMARTBILLS_API_KEY;

const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

const response = await fetch('https://api.smartbills.io/v1/user', {
  method: 'GET',
  headers: headers
});

import os
import requests

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

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.smartbills.io/v1/user',
    headers=headers
)

<?php
$apiKey = getenv('SMARTBILLS_API_KEY');

$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
];

$ch = curl_init('https://api.smartbills.io/v1/user');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);
curl_close($ch);
?>

require 'net/http'

api_key = ENV['SMARTBILLS_API_KEY']
uri = URI('https://api.smartbills.io/v1/user')

request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{api_key}"
request['Content-Type'] = 'application/json'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

package main

import (
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("SMARTBILLS_API_KEY")
    
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.smartbills.io/v1/user", nil)
    req.Header.Add("Authorization", "Bearer "+apiKey)
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

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)

Rename a Key

Update the name for better organization:

Find the key in your API keys list
Click Edit or the pencil icon
Enter a new name
Click Save

Naming convention: Use descriptive names that indicate the key’s purpose and environment, like “Production-WebApp-v2” or “Dev-Mobile-Testing”.

Revoke a Key

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
Migrating to a new key
No longer using an integration
Suspected unauthorized use

Rotate 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 to ensure everything works

Monitor

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

Revoke Old Key

Once confident the new key is working, revoke the old one This ensures no requests slip through

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

Key Permissions & 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.

Available Scopes

Business Scopes

read:businesses - View business information

List businesses
Get business details
View business settings

write:businesses - Create and modify businesses

Create new businesses
Update business information
Modify business settings

delete:businesses - Remove businesses

Delete businesses (with confirmation)

Expense Scopes

read:expenses - View expenses

List all expenses
Get expense details
Download attachments
Export expense data

write:expenses - Create and modify expenses

Upload new expenses
Update expense information
Add/remove attachments
Categorize expenses

delete:expenses - Remove expenses

Delete individual expenses
Bulk delete operations

Report Scopes

read:reports - View expense reports

List reports
Get report details
View report timeline
Access audit logs

write:reports - Create and modify reports

Create new reports
Update report details
Add/remove expenses
Submit reports

approve:reports - Approval permissions

Approve reports
Reject reports
Require changes
Add comments

User Scopes

read:user - View user information

Get own user details
View user settings

write:user - Modify user information

Update profile
Change settings

manage:users - Manage team members (admin only)

Invite users
Remove users
Update permissions

Security Best Practices

Do’s ✅

Store in Environment Variables

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

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

Use Different Keys per Environment

Development: test key
Staging: separate test key
Production: live key

Never use the same key across environments.

Rotate Regularly

Set a calendar reminder to rotate keys every 90 days.

Use HTTPS Only

Always make API requests over HTTPS to encrypt your key in transit.

Implement IP Restrictions

Restrict keys to specific IP addresses when possible.

Set Expiration Dates

For temporary integrations or testing, set keys to auto-expire.

Monitor Usage

Regularly review which keys are being used and when.

Don’ts ❌

Never do these:

❌ Commit API keys to version control (Git, SVN, etc.)
❌ Expose keys in client-side code (JavaScript, mobile apps)
❌ Share keys in emails, Slack, or other messaging
❌ 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

Accidental Exposure

If you accidentally expose an API key:

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].

Advanced Features

IP Address Restrictions

Limit API key usage to specific IP addresses:

Edit your API key
Click Add IP Restriction
Enter allowed IP addresses (one per line)
Supports both IPv4 and IPv6
Use CIDR notation for ranges: 192.168.1.0/24
Click Save

# Example IP restrictions
168.1.100
0.113.0/24
db8::/32

Production tip: For production servers, always restrict to your server’s IP addresses.

Key Expiration

Set automatic expiration dates:

When creating or editing a key
Enable Set Expiration Date
Choose expiration date and time
Key will automatically be revoked after this time

Use cases:

Temporary contractor access
Time-limited integrations
Testing periods
Project-based access

Rate Limits per Key

Each API key has its own rate limit tracking:

View current usage in API keys dashboard
Track requests per hour/day
Monitor against your plan limits
Alerts when approaching limits

See Rate Limits for details.

Troubleshooting

401 Unauthorized Error

Possible causes:

Missing Authorization header
Authorization: Bearer YOUR_API_KEY
Incorrect format
- Include “Bearer ” prefix
- No extra spaces
- Full key string
Revoked or expired key
- Check if key is still active
- Create a new key if needed
Wrong key type
- Ensure using live key for production
- Test key for testing environments

403 Forbidden Error

Reasons:

Insufficient permissions
- Your user account lacks necessary permissions
- Contact your administrator
IP restriction
- Request from unauthorized IP
- Check IP restrictions on the key
Business access
- Trying to access a business you’re not a member of
- Verify businessId parameter

Can't create API key

Possible issues:

Reached key limit
- Free plan: 2 keys max
- Professional: 10 keys max
- Enterprise: Unlimited
Solution: Delete unused keys or upgrade plan
Insufficient permissions
- Only account owners and admins can create API keys
- Request access from your administrator

Lost my API key

What to do:API keys cannot be retrieved after creation. You must:

Revoke the lost key (for security)
Create a new API key
Update your application with the new key
Test thoroughly

For security reasons, Smartbills never stores the full API key after creation.

Testing API Keys

Verify Your Key Works

Quick test to verify your API key:

curl -X GET https://api.smartbills.io/v1/user \
  -H "Authorization: Bearer YOUR_API_KEY"

Expected response (success):

{
  "id": 12345,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe"
}

Expected response (error):

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Test Environment

Use test keys in development:

Create a test API key
Set it in your development environment
Run your integration tests
Verify all functionality works
Switch to live key only for production

Migration Guide

Moving from Test to Production

Create Live Key

Generate a live API key from your dashboard.

Update Environment Variables

# Production .env
SMARTBILLS_API_KEY=sk_live_your_production_key
SMARTBILLS_ENV=production

Update Base URL (if different)

Ensure you’re pointing to production endpoint:

https://api.smartbills.io/v1

Test Thoroughly

Run integration tests in staging with live key before going to production.

Deploy

Deploy your application with the live key.

Monitor

Watch logs and error rates closely after deployment.

Authentication Guide

Complete authentication documentation

Rate Limits

Understand API rate limiting

Error Handling

Handle API errors effectively

Webhooks

Set up webhook authentication

Need Help?

Security Issues: [email protected]
General Support: [email protected]
Documentation: docs.smartbills.io
Community: community.smartbills.io

​Overview

​Creating API Keys

​Generate Your First API Key

​API Key Types

​Test Keys

​Live Keys

​Using API Keys

​Authentication Header

​Complete Example

​Managing API Keys

​View All Keys

​Rename a Key

​Revoke a Key

​Rotate Keys

​Key Permissions & Scopes

​Permission Inheritance

​Available Scopes

​Security Best Practices

​Do’s ✅

​Don’ts ❌

​Accidental Exposure

​Advanced Features

​IP Address Restrictions

​Key Expiration

​Rate Limits per Key

​Troubleshooting

​Testing API Keys

​Verify Your Key Works

​Test Environment

​Migration Guide

​Moving from Test to Production

​Related Resources

Authentication Guide

Rate Limits

Error Handling

Webhooks

​Need Help?

Overview

Creating API Keys

Generate Your First API Key

API Key Types

Test Keys

Live Keys

Using API Keys

Authentication Header

Complete Example

Managing API Keys

View All Keys

Rename a Key

Revoke a Key

Rotate Keys

Key Permissions & Scopes

Permission Inheritance

Available Scopes

Security Best Practices

Do’s ✅

Don’ts ❌

Accidental Exposure

Advanced Features

IP Address Restrictions

Key Expiration

Rate Limits per Key

Troubleshooting

Testing API Keys

Verify Your Key Works

Test Environment

Migration Guide

Moving from Test to Production

Related Resources

Need Help?