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 five blockers. They explain why capabilities remain unavailable; they do not imply that an endpoint exists:

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 25 published contract operations.
• Treat the five hosted operations as backend session security foundations only. Official UI, final order creation, provider payment progression, production configuration, and migrations are not complete.

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: Not yet available (OAuth endpoints); security model is published.

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 contains no authorization, token exchange, revocation, or grant-management endpoint and explicitly blocks release on DPoP plus resource/installation binding. This site therefore publishes no 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 guidance); Platform enablement required (real grants); Not yet available (unconfirmed capabilities such as DPoP and rotation).

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. Do not assume DPoP, refresh-token rotation, or replay detection is available.

5. Call an available API

Status: Available (11 read-only operations).

The Reference currently contains seven anonymous catalog reads and four API Key identity/catalog reads. 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. Installation identity/readiness reads and five hosted backend session operations are published; OAuth, installation writes, Webhook management, hosted UI, final order creation, and provider payment progression 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 operations are GET and require no write idempotency key; installation writes and the Orders API are not yet available.

The 20 read operations may use bounded safe retries while respecting rate limits. For hosted session mutations, follow only idempotency facts declared by the operation contract; when the spec does not declare them, treat a timeout or disconnect as an unknown outcome and do not replay blindly. These session operations do not prove that hosted UI, order creation, or payment progression is available.

8. Webhook signing, replay protection, and retries

Status: Platform enablement required (subscription and secret); Not yet available (the subscription-management endpoint still requires an installation-bound credential); verification and recovery guidance is published.

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. No self-service revocation endpoint is public today; 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.