Set up API access
1. Confirm the shop is approved for the pilot
Alva must approve the shop before API keys can be created or used. If access is not active yet, contact admin@alvaapps.com.
2. Create an API key
Open Alva Settings, choose API keys, and create a key for the integration. Copy the token once and store it in a secret manager. Alva stores only a public key id and a hash of the secret.
3. Send the token as a Bearer header
Send every request with Authorization: Bearer adk_live_.... A missing, malformed, unknown, or revoked key returns the same unauthorized response so attackers cannot enumerate valid keys.
4. Include idempotency keys on writes
Every non-GET request must include an Idempotency-Key header. Reusing the same key and body safely replays a successful response instead of creating a duplicate asset, mapping, assignment, or access change.
Create assets and map products
Use POST /api/v1/assets to ingest a remote file from an allowlisted host, or use the direct-upload endpoints when your integration uploads to Alva storage itself. Poll GET /api/v1/jobs/{job_id} until remote ingest completes.
After the asset exists, create or update a mapping with POST /api/v1/mappings. Product ids should use Shopify GID format. The API scopes every mapping to the shop attached to the API key.
Assign downloads to orders
Use POST /api/v1/orders/{shopify_order_id}/assignments when an external system needs to give a customer access to mapped digital products. The assignment can create the customer record, create the purchase, and optionally send the delivery email.
Use the order access endpoints to revoke access, restore access, grant extra downloads, or resend the delivery email. These actions are shop-scoped and do not accept shop ids in the request body.
Read the API docs
Use the quickstart, endpoint reference, error guide, and downloadable OpenAPI spec when building an integration.
FAQ
Can every merchant use the external API?
No. API access is available by approval. Contact admin@alvaapps.com to activate API access for your store.
Do write requests need idempotency keys?
Yes. Every non-GET request must include an Idempotency-Key header so retries do not create duplicate assets, mappings, assignments, or access changes.
See also
Was this helpful?
Last updated 2026-06-05