Skip to main content

Authentication

GoRoute uses API keys to authenticate requests. All API requests must include your API key in the X-API-Key header.

API Key Format​

GoRoute API keys follow this format:

pk_goroute_{32_character_random_string}

Example:

pk_goroute_b9dfe1472f85caca2631b3862418b1085437bc2a56624e47

Using Your API Key​

Include your API key in every request:

curl -X GET https://app.goroute.ai/peppol-api/api/v1/invoices \
  -H "X-API-Key: pk_goroute_your_key_here"

Python Example​

import requests

headers = {
    "X-API-Key": "pk_goroute_your_key_here",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://app.goroute.ai/peppol-api/api/v1/invoices",
    headers=headers
)

Node.js Example​

const axios = require('axios');

const response = await axios.get(
  'https://app.goroute.ai/peppol-api/api/v1/invoices',
  {
    headers: {
      'X-API-Key': 'pk_goroute_your_key_here'
    }
  }
);

C# Example​

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "pk_goroute_your_key_here");

var response = await client.GetAsync(
    "https://app.goroute.ai/peppol-api/api/v1/invoices"
);

Creating API Keys​

  1. Log in to the GoRoute Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Give it a descriptive name (e.g., "Production Backend", "CI/CD Pipeline")
  5. Copy the key immediately — it won't be shown again

API Key Best Practices​

✅ Do​

  • Store keys in environment variables or secret managers
  • Use different keys for development, staging, and production
  • Rotate keys periodically (every 90 days recommended)
  • Use descriptive names to identify key purposes
  • Revoke unused keys promptly

❌ Don't​

  • Commit keys to source control (Git, SVN)
  • Expose keys in client-side code (JavaScript, mobile apps)
  • Share keys via email or chat
  • Use the same key across multiple environments
  • Log API keys in application logs

Environment Variables​

Store your API key as an environment variable:

# Linux/macOS
export GOROUTE_API_KEY="pk_goroute_your_key_here"

# Windows PowerShell
$env:GOROUTE_API_KEY = "pk_goroute_your_key_here"

# Windows CMD
set GOROUTE_API_KEY=pk_goroute_your_key_here

Then use it in your code:

import os
API_KEY = os.environ.get("GOROUTE_API_KEY")

Key Rotation​

To rotate an API key:

  1. Create a new API key
  2. Update your application to use the new key
  3. Deploy the update
  4. Verify the new key works
  5. Revoke the old key
Zero-Downtime Rotation

GoRoute allows multiple active API keys per organization. Create the new key before revoking the old one to avoid downtime.

Error Responses​

Missing API Key​

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is required. Include X-API-Key header."
  }
}

HTTP Status: 401 Unauthorized

Invalid API Key​

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key. Check that your key is correct."
  }
}

HTTP Status: 401 Unauthorized

Revoked API Key​

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "This API key has been revoked."
  }
}

HTTP Status: 401 Unauthorized

Rate Limiting​

API keys are subject to rate limits:

TierRequests/MinuteRequests/Day
Free601,000
Starter30010,000
Business1,000100,000
EnterpriseCustomCustom

When rate limited, you'll receive:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "retry_after": 60
  }
}

HTTP Status: 429 Too Many Requests

See Rate Limits for more details.

IP Whitelisting (Enterprise)​

Enterprise customers can restrict API key usage to specific IP addresses:

  1. Go to Settings → API Keys
  2. Click on the key to configure
  3. Enable IP Whitelisting
  4. Add allowed IP addresses or CIDR ranges

Audit Logs​

All API key usage is logged. View usage in the dashboard:

  • Last used timestamp
  • Request counts
  • Error rates
  • Geographic distribution

Next Steps​