Authentication

The Billogram API is built according to RESTful principles. This guide explains how to authenticate to the Billogram API, which base URLs to use for sandbox vs production, and where to find webhook signature verification.

Security requirements

HTTPS only

• All API requests must be made over HTTPS.
• Plain HTTP requests will be rejected.
• Use the correct Base URL for your environment (see API Base URLs).

Keep credentials secret

• Your API Password (API Key) is a secret.
• Do not embed it in client-side code (e.g., browser JavaScript), public repositories, or unencrypted emails.
• Store credentials in a secure secret manager or environment variables.
• Rotate credentials immediately if you suspect they have been exposed.

Use separate API users per integration (recommended)

• Create distinct API users for each system (e.g., “Website-Integration” and “ERP-Sync”).
• This practice makes it easier to rotate or revoke access for one integration without impacting others.
• Disable API users you no longer use.

Obtaining credentials

Authentication requires an API User ID and an API Password (also referred to as an API Key). To create your credentials:

1. Log in to your Billogram account.
2. Navigate to Company Settings → API → API Users.
3. Create a new API user and copy the credentials securely.

Authentication basics

API Base URLs

As mentioned in the Getting Started guide, the API environment is determined by the Base URL.

Endpoint structure

Endpoints follow the pattern /api/v2/{resource_class}/{resource_id}.

• Example customer: /api/v2/customer/1234
• Example billogram: /api/v2/billogram/2kAEEjE

HTTP Basic Authentication

The Billogram API uses HTTP Basic Authentication for every request.

How to authenticate:

1. Concatenate your API User ID, a colon, and your API Password (e.g., API_USER_ID:API_PASSWORD).
2. Base64-encode the resulting string.
3. Add the following HTTP header to each request:

Authorization: Basic <base64(API_USER_ID:API_PASSWORD)>

Stateless requests and atomic updates

The Billogram API is stateless: each request is processed independently and must include authentication details.

For requests that modify a resource, the API applies changes atomically: the update is either fully applied or not applied at all. If the request fails, no partial update is persisted.

Examples

curl will handle the Base64 encoding automatically when you use -u:

curl -X GET "https://sandbox.billogram.com/api/v2/customer" \
  -u "YOUR_API_USER_ID:YOUR_API_PASSWORD"

Webhooks

For webhook signature verification, see Webhooks.

Errors and responses

For HTTP status codes and error response format, see Requests & Responses.