Ayomide Odewale
Ayomide Odewale
|
September 26, 2026
|
12 min read

Frontend and Mobile Integration Guide

Everything a web or mobile client needs: base URLs, URL structure, payload encryption, auth tokens, App Check, rate limits and error handling.

For web and mobile developers integrating with the Xedla API. Where to point your client, what to send, what comes back, and the things that will silently break you if you do not know about them.

Written 25 September 2026, read directly from the four service repositories and the nginx configuration, and verified against the running staging environment. Every claim here was checked against code or a live request, not assumed.

This document is self-contained. API URL Structure and Legacy Deprecation covers the same routing in more depth plus the retirement plan for the old hostnames; read that when you are planning a migration, not to get started.

Base URLs

Base URL

Staging

https://api.staging.xedla.com

Production

https://api.xedla.com

Use https://. Staging has a real, publicly trusted certificate, so no certificate exceptions are needed anywhere.

URL structure

There are two structures live in parallel. Both reach the same services.

Shape

Use it?

Canonical

api.xedla.com/v1/{service}/...

Yes. All new work.

Legacy

{service}.xedla.com/api/...

No, unless you have to. Deprecated.

{service} on the canonical host is one of auth, transactions, cards, escrow.

The version comes before the service

This is the single most common mistake:

correct    /v1/auth/users
wrong      /auth/v1/users

One hostname serves the whole API. /v1 is the public contract. Each service internally mounts its routes under /api, and the edge rewrites that away, so /api should never appear in a URL you write.

You call

The service receives

api.xedla.com/v1/auth/...

/api/v1/...

api.xedla.com/v1/transactions/...

/api/v1/...

api.xedla.com/v1/cards/...

/api/v1/...

api.xedla.com/v1/escrow/...

/api/v1/...

Worked example, taken from the auth service's own log:

you send:  GET api.staging.xedla.com/v1/auth/users
it sees:   GET /api/v1/users

Trailing slashes

/v1/auth with no trailing slash returns a 301 to /v1/auth/. Most clients follow it automatically. If yours is configured not to follow redirects, or you are doing a POST, send the trailing slash yourself rather than relying on the redirect, because not every client re-sends a body after a 301.

Only v1 is public

Every service also serves a /api/v2 tree, but it is not exposed on the canonical host. Exposing it is a decision about the public contract that has not been taken. The unversioned /api/{resource} alias is likewise not available there.

If you need either, they exist only on the legacy hostnames, and you should raise it rather than quietly depending on it.

The legacy hostnames

One hostname per service, with no path rewriting. Whatever you send arrives unchanged. This is what every currently shipped client uses.

Hostname

Service

auth.xedla.com

Auth

transaction.xedla.com

Transactions

cards.xedla.com

Virtual Cards

escrow.xedla.com

Escrow, plus Socket.IO

Mind the spelling. The legacy host is transaction, singular. The canonical path is /v1/transactions/, plural. They genuinely disagree. This is a wart, not a typo.

These are deprecated but have no removal date, and nothing will be switched off underneath a working client. Four things still only work here: Socket.IO, the /api/v2 trees, the unversioned /api alias, and /api/web. If you are writing new code, use the canonical structure; if you are maintaining an existing client, plan the move but do not panic.

Read this next: requests and responses are encrypted

In staging and production, request bodies and response bodies are AES-encrypted. Not TLS, which is separate and also on. This is an application-level envelope on top of it.

This catches every new integrator. A plain JSON POST to staging does not fail with a validation error, it fails with this:

{"status":"error","message":"Missing encrypted data",
 "error":"Request body must contain encrypted data field"}

And a successful GET does not return the object you expected. It returns this:

{"data":"fec0f92db2d0cd467ad0f577a695d94d:c395f48c3541556f907be36a6c2c1869..."}

Both captured from api.staging.xedla.com on 25 September 2026.

The envelope

Algorithm

AES-256-CBC

IV

16 random bytes per message, never reused

Wire format

<iv as hex>:<ciphertext as hex>

Request body

{"data": "<that string>"}

Response body

{"data": "<that string>"}

The plaintext inside is the JSON you would otherwise have sent or received.

Key derivation, which you must mirror exactly

The shared key is distributed out of band. Ask the backend team; it is never in a repository.

The services derive the 32-byte key like this, and your client has to do the same thing or every message will fail to decrypt:

  1. Interpret the key string as hex.

  2. If that yields exactly 32 bytes, use it directly.

  3. Otherwise, use SHA-256 of the original string.

Step 3 is the part people miss. A key that is not valid hex decodes to a short buffer, fails the length check, and falls through to the hash. Copying only step 1 produces a client that looks correct and never works.

JavaScript and TypeScript

const crypto = require("crypto");

function deriveKey(secret) {
  const buf = Buffer.from(secret, "hex");
  return buf.length === 32 ? buf : crypto.createHash("sha256").update(secret).digest();
}

function encrypt(payload, secret) {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv("aes-256-cbc", deriveKey(secret), iv);
  let out = cipher.update(JSON.stringify(payload), "utf8", "hex");
  out += cipher.final("hex");
  return iv.toString("hex") + ":" + out;
}

function decrypt(envelope, secret) {
  const [ivHex, body] = envelope.split(":");
  const decipher = crypto.createDecipheriv("aes-256-cbc", deriveKey(secret), Buffer.from(ivHex, "hex"));
  let out = decipher.update(body, "hex", "utf8");
  out += decipher.final("utf8");
  return JSON.parse(out);
}

// Sending
await fetch("https://api.xedla.com/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ data: encrypt({ email, password }, SECRET) }),
});

// Receiving
const json = await res.json();
const actual = json.data ? decrypt(json.data, SECRET) : json;

That last line matters. Not every response is encrypted, so always branch on whether data is present rather than assuming.

Put it in one place

Wrap this in a single HTTP client and never call fetch or Dio directly from feature code. Encryption, the auth header, App Check and error unwrapping all belong in one interceptor. Teams that scatter it end up with a handful of endpoints that quietly skip encryption.

What is not encrypted

Four exceptions. Getting these wrong means either sending an envelope where none is expected, or trying to decrypt something that was never encrypted.

1. Local development. Encryption is skipped entirely when the environment is local. Staging and production both have it on. So code that works against a local backend will fail against staging, and that is the single most common surprise.

2. Error responses. Any response whose status field is exactly the string "error" is returned as plaintext. That is how you can read Missing encrypted data above. Responses using other shapes, including {"success": false, ...} and the 404 handler's {"status": false, ...}, are encrypted.

3. Excluded path prefixes. These skip encryption in both directions:

/api/web
/api/admin
/api/webhooks
/api/push-notifications
/api/test-handling

4. Health endpoints. /health and /health/redis are mounted before the encryption middleware and always return plaintext.

If you are building the web dashboard, read this twice

/api/web is on that exclusion list. The web dashboard talks to the API in plaintext JSON; the mobile app does not. Confirmed live:

GET https://auth.staging.xedla.com/api/web/anything
-> {"success":false,"message":"Please login to continue"}     plaintext

There is a second consequence, and it follows from the URL structure above. The canonical host only maps /v1/{service}/... onto /api/v1/..., so there is no canonical route to /api/web at all. The web dashboard has to keep using the legacy hostnames (auth.xedla.com/api/web/...) until that is redesigned. That is a real constraint, not an oversight, and it is worth raising before anyone plans to retire the legacy hosts.

Authentication

Standard JWT bearer token.

Authorization: Bearer <access token>

The header is parsed expecting a Bearer prefix; a bare token is tolerated on some paths but do not rely on it.

Token lifetimes

These differ per environment, which will bite you if you test refresh logic only against staging:

Token

Production

Staging

Access (mobile)

5 minutes

30 minutes

Access (web)

5 minutes

5 minutes

Refresh

7 days

14 days

A five-minute production access token means refresh is not an edge case, it is the normal path. Build it first. A client that works all day in staging can fail within minutes in production purely because the access token expires six times faster.

Handle 401 by refreshing once and retrying the original request, and make concurrent requests share a single in-flight refresh rather than each firing their own.

x-header-secure-key is not for you

You will see this header in the codebase. It is a shared secret for service-to-service calls and it bypasses rate limiting. It must never ship in a client application. If someone suggests putting it in a mobile app or a web bundle, that is a security incident waiting to happen: anything in a client binary is public.

Firebase App Check

Production only, and only on the auth service. Staging does not enforce it, and the transactions, cards and escrow services do not check it at all.

X-Firebase-AppCheck: <app check token>

Excluded prefixes, which need no token even in production:

/api/web   /api/admin   /api/webhooks
/api/push-notifications   /api/test-handling
/api/feedbacks   /api/subscribe

Because staging does not enforce this, an App Check bug cannot be caught in staging. Test it deliberately against production with a debug token before release. A debug token is supported for exactly this.

Rate limits

Window

10 minutes

Production

75 requests per IP

Staging

300 requests per IP

Response

429 with {"success": false, "message": "Too many requests..."}

Standard RateLimit-* headers are returned; read them rather than counting yourself.

Two things worth knowing. The limit is per IP, not per user, so everyone behind a corporate NAT or a mobile carrier gateway shares one budget. And 75 requests per 10 minutes is not generous for a chatty app. Batch where you can, cache what you can, and do not poll.

The client IP is taken from X-Forwarded-For then X-Real-IP, both set by the edge from the real connection.

The bot filter will reject your tooling

Requests whose User-Agent matches curl, wget, python, java or go receive a 403.

This is not a permissions problem, though it looks exactly like one. It bites automated tests, Postman collections run via CLI, CI smoke tests and any HTTP library that sends a default agent. Set a browser-like User-Agent, or a named one for your app.

/health and /_upstream/ are unaffected.

Reading failures

Status

Meaning

What to do

400 with Missing encrypted data

You sent plaintext to an encrypted endpoint

Wrap the body in the envelope

400 with Invalid encrypted payload

Wrong key, wrong derivation, or malformed iv:ciphertext

Check the SHA-256 fallback

401

Access token missing or expired

Refresh once, retry once

403

App Check missing in production, or the bot filter

Check your User-Agent first

404 JSON body

Route does not exist. The body is encrypted

Decrypt before logging

404 nginx HTML page

Routing never reached a service

Wrong path, or wrong host

413

Body over 1 MB

See below

429

Rate limited

Back off, respect RateLimit-*

502

Service down or restarting

Retry with backoff

Health endpoints, and a trap

Endpoint

What it proves

api.xedla.com/health

Only that the edge is alive. Answered by nginx itself, never touches a service, so it returns 200 even if every service is down.

auth.xedla.com/health

That the auth service answered, with its own JSON including database state. Same for the other legacy hosts.

api.xedla.com/_upstream/{service}

The full chain from the edge to that service.

Do not use api.xedla.com/health as an "is the backend up" check. It is not one.

Request body limit

The edge caps request bodies at 1 MB and rejects larger ones with 413 before the application sees them. Note that encryption inflates a payload: hex encoding alone roughly doubles it. A 600 KB image will not fit. Upload large media through a dedicated upload path, not through a JSON body.

Expect short outages during deploys

Each service runs as a single container, so a deploy takes it away for roughly 6 to 18 seconds, currently longer for auth, transactions and cards. An edge deploy briefly interrupts everything. Retry with backoff on 502 and on connection errors. Do not surface these to users as hard failures.

Realtime, escrow only

Socket.IO lives on the escrow service at /socket.io/, at the root, outside /api.

wss://escrow.xedla.com/socket.io/

It is only on the legacy hostname. It has not moved to api.xedla.com and cannot until clients are released that point at the new path, because the Socket.IO client builds its handshake URL from its own path option. Websocket upgrade headers and a 3600-second timeout are configured for this route specifically.

If you are migrating your other calls to the canonical host, leave Socket.IO where it is.

Environments at a glance

Base URL

Encryption

App Check

Rate limit

Access token

Local

your own

off

off

n/a

n/a

Staging

https://api.staging.xedla.com

on

off

300 / 10 min

30 min

Production

https://api.xedla.com

on

on (auth only)

75 / 10 min

5 min

Note what only production exercises: App Check, the 5-minute access token and the tighter rate limit. Those three are exactly where a release regresses, and none of them can be caught in staging.

Before you ship

  1. Base URL is the canonical host, and paths are /v1/{service}/... with the version first.

  2. Trailing slashes are sent, or your client follows 301 on the method you use.

  3. Encryption is in one HTTP client, not scattered per call.

  4. Key derivation includes the SHA-256 fallback, not just the hex path.

  5. Responses branch on whether data is present.

  6. Token refresh is implemented, shared across concurrent requests, and tested against a 5-minute expiry rather than staging's 30.

  7. User-Agent is set to something the bot filter allows.

  8. 502 and connection errors retry with backoff.

  9. App Check is tested against production with a debug token, because staging cannot catch it.

  10. No x-header-secure-key anywhere in the client.

  11. Bodies stay under 1 MB after encryption.

  12. Socket.IO still points at escrow.xedla.com.

Getting the shared key

The encryption key and any App Check debug token come from the backend team, out of band. They are not in any repository and are not in this document. If you have been sent one over a channel that keeps history, ask for it to be rotated.

Where the routing lives

Route changes are a pull request against nginx/ in the xedla-infra repository, not a service change. Canonical routes are in snippets/api-locations.conf; the legacy hosts are in templates/20-legacy.conf.template.

Published with Braandly