Build and operate an Alkax integration
The Alkax Developer Platform groups every integration into a project. Each project starts with isolated Sandbox and Production environments, so test activity, credentials, quotas, logs, and webhooks do not cross environment boundaries.
Open the Developer Console at https://alkax.io/developers to create and manage projects.
Project model
A project is owned by either your account or an organization. Organization policy can limit project creation, available scopes, quota, credential lifetime, and production access.
Project roles are:
| Role | Typical access |
|---|---|
| Owner | Full project lifecycle, members, credentials, and settings |
| Developer | Build and operate the integration |
| Analyst | Inspect usage, health, and request logs |
| Billing viewer | Review billing-related usage |
Create your first project
- Open the Developer Console.
- Select New project and choose an account or organization owner.
- Open Credentials and issue a Sandbox credential with only the scopes you need.
- Copy the secret immediately. Alkax stores only its derived hash and cannot display it again.
- Call a sandbox fixture or use the console playground.
- Inspect Usage and Logs using the returned request ID.
Credentials and scopes
Send a server-side credential in the X-Alkax-Key header:
X-Alkax-Key: ak_test_<key-id>.<secret>
Sandbox keys begin with ak_test_; Production keys begin with ak_live_. Available scopes include:
| Scope | Allows |
|---|---|
places:read | Read place data |
geocode:read | Search and geocode |
delivery:read | Read delivery-confirmation state |
delivery:write | Create and change delivery confirmations |
Grid encode and decode are available as separate API operations using X-Alkax-Key and the places:read scope; see the Alkax Grid address guide.
Rotation creates a replacement credential. Deploy the replacement before revoking the previous key. Revocation, expiration, project suspension, and environment suspension take effect on subsequent requests.
Subscription and usage entitlement
Developer API usage is governed by the project owner's subscription and applicable organization policy.
| Plan | Developer API entitlement |
|---|---|
| Free | Sandbox only, up to 1,000 requests per month |
| Pro Monthly or Annual | Sandbox and Production, up to 50,000 requests per month |
| Enterprise | Sandbox and Production, unlimited by default |
The plan allowance is shared across all projects and environments billed to the same account. Project, organization, and environment limits can impose a lower cap. They cannot increase the subscription allowance.
When a paid subscription expires or becomes inactive, existing Production credentials receive 402 subscription_required. When the monthly allowance is exhausted, requests receive 429 quota_exceeded until the next billing period or a plan upgrade.
Deterministic sandbox
Sandbox credentials use the same authentication pipeline and endpoint contracts as Production while isolating side effects and usage.
export ALKAX_API="https://api.alkax.io"
export ALKAX_KEY="ak_test_<key-id>.<secret>"
curl "$ALKAX_API/api/v1/sandbox/fixtures/valid-high-confidence" \
--header "X-Alkax-Key: $ALKAX_KEY" \
--header "Accept: application/json"
Stable fixture identifiers include:
| Fixture | Outcome |
|---|---|
valid-high-confidence | Deliverable with high confidence |
ambiguous | Clarification recommended |
weak-access | Valid address with weak entrance or access confidence |
not-found | Unknown address |
conflicting-evidence | Conflicting evidence and low confidence |
Use sandbox fault scenarios error-403, error-404, error-409, error-429, and error-500 to test failure handling. Use an invalid or revoked credential to exercise the real 401 path.
Request IDs, usage, and logs
Every developer API response includes X-Request-Id. The same value connects the response to request logs and support diagnostics.
The console records privacy-safe metadata such as the route template, method, status, latency, quota impact, environment, and credential name. Credentials and sensitive payload fields are excluded.
Webhooks
Open Webhooks, choose an environment, enter a public HTTPS destination, and select an event type from the dropdown. Supported project events include:
delivery.confirmation.createddelivery.confirmation.cancelled
The signing secret is displayed once. Sandbox and Production use identical signing rules but different secrets.
Webhook requests include:
X-Alkax-Event-Id: <UUID>
X-Alkax-Timestamp: <Unix seconds>
X-Alkax-Signature: v1=<lowercase HMAC-SHA256>
Calculate the expected signature over <timestamp>.<raw-body>, reject stale timestamps, compare signatures in constant time, and deduplicate on the event ID. The console can send a test event, display delivery attempts and safe response excerpts, and manually redeliver a failed event.
Alkax rejects loopback, private, link-local and DNS-resolved private destinations. Redirects are not followed.
Production readiness
Before issuing a Production credential:
- confirm your subscription and Production access;
- minimize credential scopes;
- complete a successful Sandbox request;
- test failure handling and quota responses;
- verify webhook reachability and signatures;
- configure available access restrictions where appropriate;
- confirm that no
ak_test_key is present in Production configuration.
Continue with the API quickstart, authentication guide, or API reference.