Authentication and credits

Authenticate API calls, estimate access, and handle account responses safely.

API key authentication

Send your key in the X-API-Key header on every public request.

X-API-Key: astrom8_live_...

Treat keys as secrets. Keep them in server-side environment variables, use separate keys per environment, and rotate a key immediately if it may have been exposed.

Customer session authentication

Customer delivery and report-management routes use an astrom8_sess_* bearer token returned by the customer authentication flow, not an API key. The reference marks those operations with SessionBearerAuth; do not send a customer session token to API-key endpoints.

Tiers and credits

The reference declares requirements per endpoint. Some calculations are available synchronously; premium interpretation and PDF workflows may require a higher tier or debit credits after the request is accepted.

Use POST /api/v3/estimates to inspect eligibility and the estimated debit before submitting a billable capability. The actual endpoint remains authoritative: it checks tier, balance, idempotency, and debit atomically.

Common responses

Status	Meaning	What to do
400	Input failed validation.	Correct the request from the field-level error.
401	API key is missing, invalid, or disabled.	Check the key and environment.
402	The key has insufficient credits.	Add credits or use an authorized internal key.
403	The operation is not allowed for this tier.	Upgrade the tier or choose another capability.
409	An idempotent request conflicts with a prior payload.	Reuse the original payload or a new idempotency key.
429	Rate limit reached.	Respect the retry information and back off.
5xx	The service could not complete the request.	Retry only when the operation is safe to retry.

See rate limits and errors for retry and idempotency guidance.