Quick Builder Frequently Asked Questions

This article answers the most common questions about integrating with Xeni Quick Builder.

Authentication

Do I need Auth V2 for Quick Builder?

No. Quick Builder uses JWT-based SSO authentication, not the Auth V2 signature-based authentication used by the Xeni APIs. You do not need to implement HMAC signature generation or manage API keys in the same way. Instead, you generate JWT tokens and expose a validation endpoint.

What is the maximum JWT token expiry?

The maximum allowed expiry is 30 minutes from the issued-at time (iat). Tokens with an exp claim more than 30 minutes after iat will be rejected. For better security, consider using shorter expiry times of 5-10 minutes.

What algorithm should I use to sign JWT tokens?

Use HS256 (HMAC with SHA-256). This is the only supported signing algorithm for Quick Builder SSO tokens.

How long does the secret key need to be?

Your JWT secret key must be at least 32 characters long. Use a randomly generated string for maximum security.

How do I handle expired tokens?

When a user's token expires during their session, they will need to re-authenticate. Your application should:

Detect when the user needs to return to Quick Builder.
Generate a fresh JWT token on your server.
Redirect the user to the SSO URL with the new token.

Do not attempt to refresh tokens client-side. Always generate new tokens on the server.

Can I reuse JWT tokens?

No. Generate a new token for each SSO redirect. Reusing tokens increases security risk and may fail if the token expires between uses.

SSO Configuration

What is the JWT Token Field setting?

The JWT Token Field tells Xeni what field name to use when sending the token to your validation endpoint. The default value is JWTtoken. If your endpoint expects a different field name (e.g., jwtToken), update this setting in the admin panel to match.

What should the Issuer Domain be?

The Issuer Domain must exactly match the iss claim in your JWT tokens. This is typically your application's domain (e.g., partner-app.example.com). It serves as an additional verification that the token originated from your platform.

Does my validation endpoint need to be publicly accessible?

Yes. Xeni's servers send POST requests to your validation endpoint, so it must be reachable from the internet over HTTPS. It cannot be behind a VPN or firewall that blocks external traffic.

Hotel Search

Are the search endpoints the same as the Hotels API?

Yes. Quick Builder uses the same autocomplete and property search endpoints as the Xeni Hotels API:

Autocomplete: GET /hotels/api/v2/autocomplete?key={query}
Search: POST /hotels/api/v2/properties?currency=USD&page=1&limit=50&amenities=true

The request and response formats are identical.

What is the correlation ID?

The correlation ID is a value returned in the x-correlation-id response header from the autocomplete endpoint. You must include it as a header in subsequent search requests. It links the location lookup to the property search and is required for the search to succeed.

Can I search without the correlation ID?

No. The x-correlation-id header is required for all property search requests. You must call the autocomplete endpoint first to obtain it.

What currencies are supported?

Pass the desired currency as a query parameter (e.g., currency=USD, currency=EUR, currency=GBP). The API returns prices in the specified currency. If an unsupported currency is provided, the API returns a 400 error.

How does async search work?

When you set is_async: true in the search request, the API returns results progressively:

The first response may have status: "in_progress" with partial results.
Re-send the same request with the same x-correlation-id to fetch updated results.
When all suppliers have responded, the status changes to "success".

This is useful for showing users initial results quickly while more options load in the background.

General

What happens if my validation endpoint is down?

If Xeni cannot reach your validation endpoint or it returns an error, the user will not be able to access Quick Builder. Ensure your endpoint has high availability and monitor it for downtime.

Can multiple users share the same SSO session?

No. Each JWT token contains a specific user's identity. Each user must authenticate through your platform and receive their own unique token.

Is Quick Builder mobile-friendly?

Quick Builder is a responsive whitelabel experience designed to work across desktop and mobile browsers.

Where can I get help with my integration?

Contact Xeni support at customersupport@xeni.com for assistance with your Quick Builder integration.