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 URL | |
|---|---|
Staging |
|
Production |
|
Use https://. Staging has a real, publicly trusted certificate, so no certificate exceptions are needed anywhere.
There are two structures live in parallel. Both reach the same services.
Shape | Use it? | |
|---|---|---|
Canonical |
| Yes. All new work. |
Legacy |
| No, unless you have to. Deprecated. |
{service} on the canonical host is one of auth, transactions, cards, escrow.
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 |
|---|---|
|
|
|
|
|
|
|
|
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
/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.
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.
One hostname per service, with no path rewriting. Whatever you send arrives unchanged. This is what every currently shipped client uses.
Hostname | Service |
|---|---|
| Auth |
| Transactions |
| Virtual Cards |
| 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.
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.
Algorithm |
|
IV | 16 random bytes per message, never reused |
Wire format |
|
Request body |
|
Response body |
|
The plaintext inside is the JSON you would otherwise have sent or received.
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:
Interpret the key string as hex.
If that yields exactly 32 bytes, use it directly.
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.
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.
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.
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.
/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.
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.
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 youYou 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.
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.
Window | 10 minutes |
Production | 75 requests per IP |
Staging | 300 requests per IP |
Response |
|
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.
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.
Status | Meaning | What to do |
|---|---|---|
| You sent plaintext to an encrypted endpoint | Wrap the body in the envelope |
| Wrong key, wrong derivation, or malformed | Check the SHA-256 fallback |
| Access token missing or expired | Refresh once, retry once |
| App Check missing in production, or the bot filter | Check your |
| Route does not exist. The body is encrypted | Decrypt before logging |
| Routing never reached a service | Wrong path, or wrong host |
| Body over 1 MB | See below |
| Rate limited | Back off, respect |
| Service down or restarting | Retry with backoff |
Endpoint | What it proves |
|---|---|
| Only that the edge is alive. Answered by nginx itself, never touches a service, so it returns |
| That the auth service answered, with its own JSON including database state. Same for the other legacy hosts. |
| 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.
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.
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.
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.
Base URL | Encryption | App Check | Rate limit | Access token | |
|---|---|---|---|---|---|
Local | your own | off | off | n/a | n/a |
Staging |
| on | off | 300 / 10 min | 30 min |
Production |
| 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.
Base URL is the canonical host, and paths are /v1/{service}/... with the version first.
Trailing slashes are sent, or your client follows 301 on the method you use.
Encryption is in one HTTP client, not scattered per call.
Key derivation includes the SHA-256 fallback, not just the hex path.
Responses branch on whether data is present.
Token refresh is implemented, shared across concurrent requests, and tested against a 5-minute expiry rather than staging's 30.
User-Agent is set to something the bot filter allows.
502 and connection errors retry with backoff.
App Check is tested against production with a debug token, because staging cannot catch it.
No x-header-secure-key anywhere in the client.
Bodies stay under 1 MB after encryption.
Socket.IO still points at escrow.xedla.com.
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.
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