Skip to main content

Make your first API request

This quickstart uses a Developer Platform project and its deterministic Sandbox. It exercises the same authentication pipeline as Production without creating production side effects.

Before you begin​

You need:

  • an Alkax account with access to the Developer Console;
  • a project and its Sandbox environment;
  • a Sandbox credential with delivery:read for the first fixture;
  • a backend or secure server environment;
  • the API base URL: https://api.alkax.io.

Keep credentials in a secret manager and redact them from application logs.

Open https://alkax.io/developers, create a project, and issue a Sandbox credential from Credentials. Copy the secret when it is shown; it cannot be recovered later.

Set your request variables​

export ALKAX_API="https://api.alkax.io"
export ALKAX_API_KEY="ak_test_<key-id>.<secret>"

Make a deterministic Sandbox request​

Call a versioned fixture that is safe to run from local development and CI:

curl "$ALKAX_API/api/v1/sandbox/fixtures/valid-high-confidence" \
  --header "X-Alkax-Key: $ALKAX_API_KEY" \
  --header "Accept: application/json"

The response includes a stable fixture result and an X-Request-Id header. Use that request ID to find the request in the Developer Console Logs tab.

Other stable fixtures are ambiguous, weak-access, not-found, and conflicting-evidence. The console playground can run the same fixtures and generate curl, TypeScript, Python, and C# examples.

Move to a business endpoint​

Issue a credential with only the required scope, then call the endpoint using the same X-Alkax-Key header. For pre-dispatch recipient confirmation, follow the Delivery Intelligence guide.

Do not use a Sandbox key in Production. When the integration is ready, activate a paid subscription and issue a separate ak_live_ credential from the Production environment.

Handle the response​

  • Treat the HTTP status as the primary outcome.
  • Persist stable IDs, machine-readable error codes, and the request ID.
  • Use retry-safe identifiers where a guide requires them.
  • Back off on 429 and transient 5xx responses.
  • Never retry an invalid request unchanged.

See Errors and retries for the common response model.

Continue​

Complete a working integration​

After the first Sandbox request, continue with the delivery and return integration and webhook cookbook. The fixture is an address example; it does not create a shipment. Use the documented versioned APIs and Sandbox flows to exercise a complete synthetic lifecycle before moving to Production.