Authentication

All API requests require authentication using a Bearer token. This guide shows you how to create and use API tokens.

Creating an API Token

1. Log in to your InvoisX dashboard
2. Navigate to Settings > API Tokens
3. Click Create New Token
4. Configure your token:
   • Name: A descriptive name (e.g., "Production Integration", "Testing")
   • Expiration: Set an expiration date (recommended: 1 year)
   • Permissions: Select the required permissions:
     • Create: Create new resources (buyers, invoices, etc.)
     • Read: View resources
     • Update: Modify existing resources
     • Delete: Remove resources
5. Click Create Token

Important

Copy and save your token immediately. It's displayed only once and cannot be retrieved later. If you lose it, you'll need to create a new token.

Using the Token

Include the token in the Authorization header of every API request:

Node.js

const response = await fetch('https://invoisx.com/api/v1/buyers', {
  headers: {
    'Authorization': 'Bearer your-api-token-here',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

Python

import requests

headers = {
    'Authorization': 'Bearer your-api-token-here',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://invoisx.com/api/v1/buyers',
    headers=headers
)

PHP

use Illuminate\Support\Facades\Http;

$response = Http::withToken('your-api-token-here')
    ->accept('application/json')
    ->get('https://invoisx.com/api/v1/buyers');

Java

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://invoisx.com/api/v1/buyers"))
    .header("Authorization", "Bearer your-api-token-here")
    .header("Accept", "application/json")
    .GET()
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

C#

using var client = new HttpClient();

client.DefaultRequestHeaders.Add("Authorization", "Bearer your-api-token-here");
client.DefaultRequestHeaders.Add("Accept", "application/json");

var response = await client.GetAsync("https://invoisx.com/api/v1/buyers");

Required Headers

Every API request should include these headers:

Header	Value	Required
Authorization	Bearer {token}	Yes
Accept	application/json	Yes
Content-Type	application/json	For POST/PUT requests

Token Security Best Practices

1. Never expose tokens in client-side code - Keep tokens on your server
2. Use environment variables - Don't hardcode tokens in source code
3. Rotate tokens regularly - Create new tokens and revoke old ones
4. Use minimal permissions - Only grant permissions you need
5. Monitor token usage - Review API logs for unusual activity

Environment Variables Example

.env

INVOISX_API_TOKEN=your-api-token-here
INVOISX_API_URL=https://invoisx.com/api/v1

Node.js

const apiToken = process.env.INVOISX_API_TOKEN;
const apiUrl = process.env.INVOISX_API_URL;

Python

import os

api_token = os.environ.get('INVOISX_API_TOKEN')
api_url = os.environ.get('INVOISX_API_URL')

PHP

$apiToken = env('INVOISX_API_TOKEN');
$apiUrl = env('INVOISX_API_URL');

Authentication Errors

Error Code	HTTP Status	Cause	Solution
UNAUTHORIZED	401	Missing or invalid token	Check your token is correct
TOKEN_EXPIRED	401	Token has expired	Create a new token
FORBIDDEN	403	Token lacks required permissions	Update token permissions
COMPANY_ACCESS_DENIED	403	Token not linked to correct company	Create a new token for this company

Error Response Example

{
  "success": false,
  "message": "Unauthenticated.",
  "error_code": "UNAUTHORIZED"
}

Revoking Tokens

To revoke a token:

1. Go to Settings > API Tokens
2. Find the token you want to revoke
3. Click the Revoke button
4. Confirm the action

WARNING

Revoking a token is immediate and cannot be undone. Any applications using the token will immediately lose access.

Next Steps

Now that you have your API token, you're ready to:

1. Quick Start - Submit your first invoice
2. API Reference - Explore all endpoints