Authentication
All API requests require a valid API key passed as a Bearer token.
Bearer token
Include your API key in the Authorization header
of every request:
Authorization: Bearer YOUR_API_KEY
Replace YOUR_API_KEY with your actual key from the dashboard.
Test vs live keys
GovData issues two types of API keys:
| Type | Prefix | Rate limit | Use case |
|---|---|---|---|
| Test | gd_test_ |
10 req/min | Development and testing |
| Live | gd_live_ |
Per plan | Production applications |
Example request
curl -H "Authorization: Bearer gd_test_abc123..." \ https://api.govdata.dev/v1/tax/income/bands
require "net/http" uri = URI("https://api.govdata.dev/v1/tax/income/bands") req = Net::HTTP::Get.new(uri) req["Authorization"] = "Bearer gd_test_abc123..." res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
import requests response = requests.get( "https://api.govdata.dev/v1/tax/income/bands", headers={"Authorization": "Bearer gd_test_abc123..."} )
const response = await fetch( "https://api.govdata.dev/v1/tax/income/bands", { headers: { "Authorization": "Bearer gd_test_abc123..." } } );
Authentication errors
Missing header — 401
No Authorization header was provided.
{ "error": { "code": "unauthorized", "message": "Missing or malformed Authorization header. Expected: Bearer <api_key>", "documentation_url": "https://docs.govdata.dev/errors" } }
Invalid key — 401
The API key doesn't match any active key.
{ "error": { "code": "unauthorized", "message": "Invalid API key.", "documentation_url": "https://docs.govdata.dev/errors" } }
Security best practices
- Never expose API keys in client-side code or public repositories
- Use environment variables to store keys
- Use test keys during development, live keys only in production
- Rotate keys periodically from your dashboard