Enterprise integration journey
This is a go-live decision path, not an endpoint catalog. Every stage distinguishes Available, Platform enablement required, and Not yet available. Only operations sourced from the public-only artifact in the API reference are available.
Current authoritative blocker snapshot
The API public-only artifact declares three blockers. They explain why capabilities remain unavailable; they do not imply that an endpoint exists:
| Capability | Current blocker |
|---|---|
| Installation write API | A sender-constrained installation credential is still required |
| Final order creation | A reviewed public final-order contract is still required |
| Production activation | External readiness has not been proven |
1. Pre-integration checks
Status: Available (assessment guidance); Platform enablement required (commercial and production eligibility).
- Decide whether the use case needs anonymous catalog reads, server-side API Key reads, or user authorization/write capabilities that are not yet available.
- Identify the data controller, end users, store/resource boundary, markets, and retention obligations.
- Assign technical, security, and incident contacts; define responses for credential exposure, rate limiting, and unknown write outcomes.
- Keep the current implementation scope to the 59 published contract operations.
- Use hosted, cart/quote, and order operations only as their public contracts declare. Official hosted UI, final order creation, and payment execution are not declared by the artifact.
Proceed when: every required capability has a public Reference or a written enablement path from the platform. Otherwise stop; do not infer APIs from console traffic or the mixed OpenAPI candidate.
2. Request an app and environment
Status: Platform enablement required.
Apps, environments, API Keys, installations, production eligibility, and associated capabilities are configured or approved by Ayalink. There is no public application-management endpoint. Provide the app name, use case, required markets, callback domains, technical/security contacts, and a least-privilege justification. Receive secrets only through the approved secure delivery path.
Proceed when: the target environment, allowed capabilities, credential delivery, and rotation instructions are explicit. A documentation page, client ID, or successful CORS request is not production authorization.
3. Official authorization domain and PKCE
Status: Available (OAuth PKCE/DPoP contract); Platform enablement required (real app and official-domain configuration).
When user authorization is required, send users only to the official Ayalink authorization domain confirmed in platform enablement materials. Use Authorization Code with PKCE S256, exact redirect URIs, and fresh validated state and nonce values. A third party must never proxy or imitate sign-in or collect passwords/MFA.
The current public-only artifact includes authorization description, token exchange, and revocation operations and explicitly requires PKCE S256 with DPoP. Use only the corresponding API reference and platform enablement materials; this site invents no server URL, scope, curl command, or successful response. See the OAuth and account security boundary.
Stop when: the official domain, client configuration, or exact redirect URI has not been confirmed by the platform. Do not implement an OAuth redirect or token exchange.
4. Token security and BFF
Status: Available (security architecture and DPoP contract); Platform enablement required (real grants); undeclared rotation semantics must not be assumed.
Browsers must not hold a client secret or place access/refresh tokens in URLs, persistent browser storage, logs, analytics, or error reports. For browser sessions, use a same-origin BFF. It stores only its own app grant and issues its own HttpOnly, Secure, appropriately SameSite session Cookie. It never accepts or forwards the global Ayalink Cookie.
Confirm token audience, resource boundaries, lifetime, rotation, and revocation from enablement materials. The artifact declares DPoP; do not assume refresh-token rotation or replay detection when the spec is silent.
5. Call an available API
Status: Available (59 public-only operations).
The Reference contains catalog reads, installation identity/readiness, hosted backend foundations, API Key catalog, carts/quotes, order read/cancellation/after-sales, Webhooks, and OAuth PKCE/DPoP. Use the real method, path, authentication, parameters, and response schema on each operation page. Do not copy or guess a Base URL from this guide; obtain the runtime address from platform enablement materials.
- Browse the available API catalog.
- Keep API Keys in an approved server-side header, never in a browser bundle or URL.
- Send only parameters declared by the Reference; do not invent examples for missing schemas.
Proceed when: the target operation is in the current catalog and its authentication has been enabled. Official hosted UI, final order creation, payment execution, and installation writes absent from the artifact remain unavailable.
6. Pagination, errors, requestId, and 429
Status: Available (subject to each operation's public contract).
Implement pagination parameters, cursors, and response shapes only when the operation page declares them. If the spec is silent, do not assume page, limit, cursor, or a total count. Branch on HTTP status and stable machine codes, not human-readable text. Preserve any requestId or correlation identifier actually returned for support and reconciliation. If its field/header is not declared, follow platform materials rather than inventing one.
For 429, honor Retry-After only when the response actually provides it; otherwise use bounded exponential backoff with jitter and a retry budget. Recovery boundaries for 401, 403, 404, 409/412, 422, 429, and 5xx are in errors, idempotency, and rate limits.
7. Idempotency and unknown outcomes
Status: Available reads and writes follow each operation's idempotency declaration.
Reads may use bounded safe retries while respecting rate limits. Cart, order, Webhook, OAuth, and hosted mutations follow only idempotency facts declared by their operation contracts; when the spec is silent, treat a timeout or disconnect as an unknown outcome and do not replay blindly.
8. Webhook signing, replay protection, and retries
Status: Available (subscription management and delivery query/replay contracts); Platform enablement required (installation credential and signature material).
The receiver verifies HMAC over the raw body with the timestamp and signature material declared by the platform, uses constant-time comparison, enforces the accepted time window, and atomically deduplicates the event ID. Do not parse JSON before the signature passes. During rotation, accept a current/previous key window only when the platform explicitly allows it.
Delivery retry counts, time windows, header names, and dead-letter behavior come from enablement materials. Local processing uses bounded backoff, honors an actually received Retry-After, retains the original event ID, and keeps business effects idempotent. See the Webhook guide and verification example.
9. Test and accept
Status: Available (static contract tests); Platform enablement required (real environment integration).
Cover successful reads, empty results, invalid/revoked credentials, authorization denial, missing resources, validation errors, 429, 5xx/disconnects, pagination boundaries, and log redaction. For Webhooks, also cover invalid signatures, expired timestamps, duplicate and out-of-order events, retries, and secret rotation. Never use production secrets or real personal data in tests.
Proceed when: contract tests use the current artifact; environment tests record requestId, time, operationId, and redacted results; every unknown outcome can be reconciled or stopped safely.
10. Production go-live checks
Status: Platform enablement required; external readiness has not been proven.
- The platform has confirmed the production app/environment, allowed capabilities, markets, and credential status.
- Base URL, authorization domain, redirect URIs, audience, scopes, and Webhook parameters come from platform materials, not documentation guesses.
- Credentials are in a secret manager; logging, monitoring, alerting, rotation, rate-limit budgets, and incident contacts are ready.
- Recheck the current API Reference source version and change notes before production.
- Canary, rollback, and stop conditions have owners. Test success does not equal production approval.
11. Revocation and incident response
Status: Platform enablement required (revocation entry point and support); security response guidance is published.
For an exposed token/API Key/Webhook secret, abnormal traffic, a phishing authorization page, or suspected cross-boundary access: stop affected traffic, isolate the leak, revoke or rotate credentials through the approved platform entry point, preserve requestId, operationId, time range, and redacted logs, and contact the official security channel. Never paste tokens, Cookies, or full payloads into a ticket.
Before resuming, prove old credentials are invalid, consumers are updated, duplicate events/unknown writes are reconciled, the root cause is fixed, and the production checklist has been repeated. The OAuth revocation operation is now in the public Reference. Use platform enablement materials for every other credential or installation revocation entry point; do not guess a URL or treat deleting a local Cookie as revoking a grant.
Automatic Reference expansion
When a later API public-only artifact arrives, the importer verifies its source commit, hash, operationId, security schemes, and internal boundaries before generating additional bilingual endpoint pages. This guide updates availability only from real artifacts; it does not wait for a full catalog or hand-write endpoints, scopes, or responses.