Authentication

The GenerateInvoice API uses API keys to authenticate requests. You can view and manage your API keys in your account dashboard.

API Key Authentication

Authentication to the API is performed via HTTP Bearer authentication. Provide your API key as the bearer token in the Authorization header.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.generateinvoice.io/api/v1/invoices

How to Get Your API Key

Log in to your GenerateInvoice dashboard
Navigate to Settings in the sidebar
Click on API Keys
Click Create New Key
Give your key a descriptive name (e.g., "Production Server")
Choose the environment (Test or Live)
Copy your new API key immediately - it won't be shown again!

Important Security Notice

Your API key carries many privileges. Keep it secure! Do not share your secret API key in publicly accessible areas such as GitHub, client-side code, or anywhere else.

Key Format

GenerateInvoice API keys have a specific format to help you identify them:

Environment	Prefix	Example
Live	`gi_live_`	`gi_live_a1b2c3d4e5f6...`
Test	`gi_test_`	`gi_test_x9y8z7w6v5u4...`

Request Headers

Include these headers in every API request:

Header	Required	Description
`Authorization`	Yes	Bearer token with your API key
`Content-Type`	For POST/PATCH	Must be `application/json`

Every error response includes an X-Request-Id header, and every response carries request_id in the body (header support on successes is rolling out endpoint by endpoint). Include it when contacting support about a specific request.

Test vs Live Keys

Keys come in two flavors, distinguished by prefix: gi_test_ and gi_live_.

Heads up: test keys currently behave exactly like live keys — documents count against your usage limits and PDFs carry no watermark. Sandbox semantics (no usage counting, TEST watermark, test-data separation) are on the roadmap. Until then, treat every key as live.

Best Practice

Until sandbox semantics ship, develop against a separate account (or accept that dev documents count toward your quota). Rotate any key that may have leaked.

Code Examples

Here are examples of how to authenticate in different programming languages:

# Using Bearer authentication
curl -X GET "https://www.generateinvoice.io/api/v1/invoices" \
  -H "Authorization: Bearer gi_live_your_api_key_here"

# With additional headers
curl -X POST "https://www.generateinvoice.io/api/v1/invoices" \
  -H "Authorization: Bearer gi_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to_details": {"name": "Customer"}, "line_items": [...]}'

Storing API Keys Securely

Never hardcode your API keys in your source code. Instead, use environment variables:

.envbash

# Never commit this file to version control!
GENERATEINVOICE_API_KEY=gi_live_your_api_key_here

# You can also separate test and live keys
GENERATEINVOICE_TEST_KEY=gi_test_your_test_key_here
GENERATEINVOICE_LIVE_KEY=gi_live_your_live_key_here

Revoking API Keys

If you believe your API key has been compromised, revoke it immediately:

Go to Settings → API Keys in your dashboard
Find the compromised key
Click the Revoke button
Create a new API key
Update your application with the new key

Revoked keys are immediately invalidated. Any requests using a revoked key will receive a 401 Unauthorized response.

Authentication Errors

When authentication fails, the API returns one of these error codes:

Error Code	HTTP Status	Description
`UNAUTHORIZED`	401	No API key was provided
`INVALID_API_KEY`	401	The key format is wrong or the key does not exist
`API_KEY_EXPIRED`	401	The API key has expired

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked."
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}