Authentication

Meterd supports three authentication methods. Choose the one that fits your use case.

Bearer Token (API Key)

The simplest method. Include your API key in the Authorization header:

bash

curl -H "Authorization: Bearer mtd_adm_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345" \
  https://api.meterd.io/v1/meters

API keys follow the pattern mtd_<scope>_<32 random chars>:

Prefix	Scope	Permissions
`mtd_adm_`	Admin	All operations
`mtd_rw_`	Read/Write	Read and write events, meters, customers, usage, quotas
`mtd_ro_`	Read Only	Read usage, meters, customers
`mtd_ink_`	Ingest Only	Ingest events only

Operation	Endpoint	Notes
Create	`POST /v1/api-keys`	Full key shown once — store securely
List	`GET /v1/api-keys`	Returns metadata only (prefix, scope)
Revoke	`POST /v1/api-keys/:id/revoke`	Immediate invalidation
Rotate	`POST /v1/api-keys/:id/rotate`	Revokes old, returns new

For service-to-service communication with request integrity verification.

Header	Description
`Authorization`	HMAC v1:<base64_signature>
`X-Timestamp`	Unix timestamp (within 300s of server time)
`X-Request-Id`	Unique request identifier
`X-Tenant-Id`	Your tenant ID

The signature is computed over <timestamp>:<request_id>:<body> using HMAC-SHA256 with your shared secret.

The server rejects requests where the X-Timestamp is more than 5 minutes from the server clock. Keep your systems' clocks synced via NTP.

Role	Description
Owner	Full access including tenant management. One per tenant.
Admin	Everything except tenant settings
Developer	Ingest events, manage meters/customers/webhooks/alerts
Billing	Read access + manage billing
Viewer	Read-only access to usage, meters, and customers

Authentication failures return RFC 7807 Problem Details:

json

{
  "type": "https://meterd.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired API key"
}

Status	Meaning
`401`	Missing or invalid credentials
`403`	Valid credentials but insufficient permissions