Capture request context headers
Every call to the MatchMove Banking Operating System (BOS) API comes from your backend. MatchMove never sees the person, device, or network behind an action unless you forward that information. Request context headers carry it. You send one header that says who the request is on behalf of (an end user, one of your operators, or an automated system) and, for end-user actions, three more that carry the user's IP address, a device identifier, and a client descriptor. The rules for each actor type are below.
Why these headers are needed
MatchMove is a licensed financial institution, and in most markets so are you. Several obligations both of us carry depend on knowing who acted, from where, and on what device. When your backend is all the platform can see, none of them can be answered from MatchMove's records.
- Transaction monitoring. Anti-money-laundering and counter-terrorism financing (AML/CFT) monitoring scores an action against the behavior of the person taking it. Velocity, impossible travel, and multi-accounting patterns stay invisible while every request carries your server's IP address.
- Audit trail. Retention rules require a transaction to be reconstructable years after it settled, including the actor behind it. A datacenter IP address identifies no one, and the record cannot be corrected later.
- Fraud and scam liability. The scam frameworks in force across the region assume a platform can tell a device it has seen before from one it has not and can challenge an action when it cannot. That rests on the device identifier alone.
- Reporting obligations. Where MatchMove has to account for how an account was accessed, the answer is limited to what your integration forwarded at the time. That includes suspicious transaction reporting, where a filing naming the account but not the device or network behind it is materially weaker.
The obligations run both ways. These values are also the evidence your compliance team needs to demonstrate the controls on your program.
These headers are the first of several changes to how you authenticate to and describe requests to the platform. Additional authentication modes for tighter security and simpler credential management are coming in later releases, and the context you send today carries over unchanged.
How it works
Your integration is server-to-server. Your backend authenticates to MatchMove with its API credential and calls the API for the person or process that triggered the action. Three things follow:
- The source IP that reaches MatchMove is your server's, not the user's.
- MatchMove has no connection to the user's device and cannot observe it.
- The standard
User-Agentheader on your call describes your HTTP library (okhttp/4.12.0,axios/1.7.2), not the user's client.
The request context headers close that gap. The flow for a user-initiated action is:
- The user acts in your app or website. Your client sends the request to your backend along with a device identifier it has stored.
- Your backend records the user's IP from its own edge, the device identifier, and the client's user agent, at the moment the action arrives.
- Your backend validates the three values, then calls MatchMove with
X-Auth-Actor: end-userand the three context headers. - MatchMove records them against the acting user and uses them in risk evaluation. Once enforcement is in effect, a missing or invalid value is rejected with
400.
For an operator or system action, there is no user IP, device, or client to capture. You send X-Auth-Actor with an identifier for the operator or system and omit the three context headers.
Actor types
| A person using your app, website, or an assisted channel initiated the action. | Endpoints that act on a customer's own account, such as onboarding, card lifecycle, transfers, and balance reads. | Login, Know Your Customer (KYC) submission, transfer, card freeze, PIN reset, beneficiary change, limit change. |
| One of your staff initiated the action from your own tooling, whether or not it affects a customer. | Any endpoint, including program configuration. | Compliance override, support-initiated card replacement, manual KYC review. |
| An automated process initiated the action. No person is behind it. | Any endpoint, including program configuration. | Batch settlement, reconciliation, webhook acknowledgement, balance polling. |
Not every endpoint can have a person behind it. Program configuration, prefund, card product setup, webhook subscription, and report retrieval are called by your operators or your systems, never by a customer, so end-user is never a true statement on them. Each endpoint's reference page lists the actors it accepts, in one line: Actors: operator, system.
Everywhere else, the same endpoint takes a different actor depending on who triggered the call. A card suspension from your support tool is operator. The same call from your app is end-user with all three context headers. Your system polling a balance overnight is system; the user viewing that balance in your app is end-user.
A request with no X-Auth-Actor is treated as end-user. That is the strict path: the three context headers are then required. Once enforcement is in effect, automated traffic that does not send the actor header is rejected for missing context. Add X-Auth-Actor: system to it. Set the actor per call site, not once as a client-wide default, so machine-only calls carry operator or system.
Warning:
- Never declare
operatororsystemon an action a person initiated to avoid capturing their context. System-declared traffic on end-user operations gets the strictest risk treatment, never the relaxed one. - Never send made-up end-user values. They are worse than no value. A datacenter IP misrepresents the audit trail, a random device identifier makes device history unbuildable, and one identifier shared across many users looks like multi-accounting fraud and triggers automatic account locks against your own customers.
The four headers
X-Auth-Actor answers who the request is on behalf of, and goes on every call. The other three answer questions about an end user's session: X-Auth-User-IP say from what network the user acted, X-Auth-Device-ID says from which device, and X-Auth-User-Agent says what client they used, on what platform, and at what version. Much of their risk value comes from checking them against one another. A device identifier with iOS history that shows up with an Android user agent is only visible when all three are present. Send all three whenever the actor is end-user; none substitute for another.
These rules apply to every context header:
- Send
X-Auth-Actoron every request. Send the other three only when the actor isend-user. - Capture each value fresh when the action reaches your backend. Never make one up, and never pass a client value through without checking it.
- Send one value per header, exactly as you captured it.
Rules by header:
X-Auth-Actor
- The operator and system need an ID.
- The end-user must not have one.
- The type and the ID are case-sensitive.
- Do not use an email address, a person's name, or your program code as the ID.
X-Auth-User-IP
- Send the one address to your own edge saw.
- Private and internal ranges are accepted, but they give no risk signal.
- Do not add a port, a CIDR suffix, brackets, or a second address.
- Do not send your own server's address.
X-Auth-Device-ID
- Pick one case convention and keep to it. Values are compared exactly.
- The value should mean nothing on its own.
- Do not use hardware IDs (IMEI, MEID, serial, MAC, ICCID) or advertising IDs (IDFA, GAID).
- Do not use contact details or anything built from the user's identity.
- Do not add your tenant name. MatchMove does that on receipt.
X-Auth-User-Agent
- Keep it under 1024 bytes. Longer values are rejected, not shortened.
- Send it exactly as you received it. No re-casing, encoding, or wrapping.
- Short strings from privacy-focused browsers are fine. Pass them on unchanged.
- Do not send your HTTP library's user agent or a string you rebuilt yourself.
- Do not send device nicknames, account numbers, tokens, location, or free text the user typed.
The table below gives the shape of each value. The integration guide that follows explains how to capture each one.
| Required on every request |
|
| Required when Do not pass the header for |
|
| Required when Do not pass the header for |
|
| Required when Do not pass the header for |
|
Integration guide
MatchMove does not publish client-side software development kits (SDKs), so capture, persistence, and forwarding are yours to build. MatchMove's risk models are tuned against the approach below. Copy it rather than inventing a variant.
1. X-Auth-Actor: Declare the actor on every request
Add X-Auth-Actor to every outbound MatchMove call. It is a backend-only change, and it is what lets MatchMove tell your automated traffic from your users' traffic.
For end-user, send the type alone. For operator and system, add an id parameter.
X-Auth-Actor: end-user
X-Auth-Actor: operator; id=op_7f3a9c21
X-Auth-Actor: system; id=treasury-monitor-prod-0001
The operator ID is an opaque value from your own staff directory. Do not send an email address or a person's name; the value lands in logs and Console activity views. The system ID names the calling system, environment, and instance. Use a distinct ID per backend system so audit trails stay legible.
Make the actor a required argument of your MatchMove client so a call site cannot omit it, and do not hardcode a client-wide default. A default of end-user breaks your machine-only calls; a default of system misdeclares your users' actions.
2. X-Auth-User-IP: Capture the end user's IP address
Read the user's IP on your own edge, per request, at the moment the action arrives. Then forward that single value in X-Auth-User-IP.
Do not use X-Forwarded-For to carry the IP to MatchMove. MatchMove's edge (Amazon CloudFront in front of an Application Load Balancer) appends to and rewrites X-Forwarded-For in transit, so anything you put there is overwritten or indistinguishable from infrastructure hops. X-Auth-User-IP passes through unmodified.
Five rules:
- Per request, not per session. A mobile user's IP changes between cellular and Wi-Fi and across carrier network address translation (NAT) pools. A login-time IP cached for the session produces false risk signals.
- Resolve it from your own trusted proxy chain. If your client reaches your backend through a content delivery network (CDN) or load balancer, take the leftmost untrusted entry of your own
X-Forwarded-For, or your provider's dedicated header (CF-Connecting-IP,True-Client-IP,X-Real-IP). Never trust a header your client app supplies; an app can spoof any header your server accepts. - Prefer the network-observed IP. The address your edge sees on the TCP connection is far harder to forge than one the app reports about itself.
- On retry, resend the original. If you retry a failed call for the same user action, send the IP captured at the original action, not the IP at retry time.
- On web, capture server-side. Take it when the browser calls your backend. Do not have the browser ask a third-party "what is my IP" service; it is spoofable and adds a data-sharing dependency.
3. X-Auth-Device-ID: Generate and persist a device identifier
The device identifier is the highest-value signal in the risk stack because it persists where IP addresses do not. It tells MatchMove which device acted, independent of who is signed in. Your client generates it once, stores it so it survives restarts, and sends it to your backend with every action.
The identifier must describe the device and nothing else. Derive it from the user and it becomes a second user identifier, silently defeating the multi-accounting detection it exists to support. Requests carrying a hardware identifier (IMEI, MEID, serial number, MAC address, SIM ICCID, Build.SERIAL), an advertising identifier (IDFA, GAID), contact details, or anything derived from the user's identity are rejected. Their use also breaches Apple App Store and Google Play policy, and the data protection laws in MatchMove's markets.
The algorithm is the same on every platform:
- Read the persisted identifier from platform storage.
- If present and well-formed, return it.
- If absent or malformed, generate a UUIDv4 from a cryptographic random number generator, persist it, and return it.
- Guard the read, generate, and persist path with a lock so two concurrent first-launch callers cannot create two identifiers.
- Cache in memory for the process lifetime. Never regenerate mid-process.
The identifier should persist across app restart, device reboot, OS update, session expiry, and a different user logging in. It should reset on factory reset, restore from backup onto a new handset, clear browser data, and reinstall Android app. The same user on a phone and a tablet produces two distinct values. Never rotate it on a schedule, per session, or per request; a rotating value is indistinguishable from a fraud pattern.
4. X-Auth-User-Agent: Build the user agent
The user agent is descriptive, not identifying. It tells MatchMove what kind of client acted, on what platform, and at what version. Unlike the device identifier, it is expected to change on every app release and browser update. Its value comes from being truthful and verbatim.
Do not overwrite the standard User-Agent on your outbound MatchMove call. HTTP libraries set it themselves, connection pools reset it, and MatchMove's edge uses it for client diagnostics. X-Auth-User-Agent is a separate field that passes through unmodified.
The format depends on the channel.
- Web browser. Forward the browser's
User-Agentexactly as your server received it. Do not normalize, re-case, strip tokens, or rebuild it from a parsing library. The EMV 3-D Secure (3DS) browser channel carries this field, and the card issuer's risk engine compares it against what the browser itself reports. A reconstructed string does not match. Reduced strings from privacy-focused browsers are expected; forward them as-is.
X-Auth-User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36- Native mobile app. There is no browser user agent. Build a product token following RFC 9110 syntax. Use the machine-readable device model (
iPhone15,3,SM-S918B), not the marketing name; marketing names vary by region and cannot be parsed.
<app-name>/<app-version> (<platform> <os-version>; <device-model>; build:<build-number>)
X-Auth-User-Agent: PartnerPay/4.2.1 (iOS 17.5; iPhone15,3; build:4210)
X-Auth-User-Agent: PartnerPay/4.2.1 (Android 14; SM-S918B; build:4210)- Hybrid app or embedded webview. Send the webview's user agent with your app token appended. This keeps the browser engine visible while identifying the wrapper.
X-Auth-User-Agent: Mozilla/5.0 (Linux; Android 14; SM-S918B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/127.0.6533.103 Mobile Safari/537.36 PartnerPay/4.2.1- React Native and cross-platform frameworks. Use the native format and append a framework token.
X-Auth-User-Agent: PartnerPay/4.2.1 (iOS 17.5; iPhone15,3; build:4210) ReactNative/0.76.1
- Assisted and non-browser channels. Where the user has no client software in hand (a branch agent, interactive voice response (IVR), unstructured supplementary service data (USSD), a kiosk), do not fabricate a browser string. Send a channel descriptor instead. Assisted channels carry a different risk profile from self-service; declaring them gets them scored correctly, disguising them as browser traffic gets them scored as anomalies
X-Auth-User-Agent: PartnerPayAgent/2.1 (channel:agent-assisted; terminal:BR-SG-041)
X-Auth-User-Agent: PartnerPayIVR/1.0 (channel:ivr)
X-Auth-User-Agent: PartnerPayUSSD/1.0 (channel:ussd; gateway:globe-ph)
X-Auth-User-Agent: PartnerPayKiosk/3.4 (channel:kiosk; terminal:KIOSK-MNL-12)Channel values. Whichever format you send, the channel: token names the channel. Recognized values:
web(browser)mobile-app(native app)hybrid(app webview)agent-assisted(customer served by agent)ivr(automated phone line)ussd(phone code menu)kiosk(self-service terminal)pos(point of sale)partner-portal(your own web portal)
Deferred actions. If a queued job completes something a user submitted earlier, forward the user agent and IP recorded at submission, not values observed when the job runs. Persist all three context values alongside the job.
5. Validate before you forward
Your client sends the device identifier and user agent to your backend, which forwards them to MatchMove. Validate at that boundary. Never pass a client value through unchecked, and never let your own HTTP library's user agent leak into the field.
On web, prefer the server-side cookie over anything the page sends in a request body. On mobile the client value is the only source available, which is why the identifier is a risk signal and not an authentication factor.
6. Send the request
Attach the actor header and, for end-user, the three context headers to the MatchMove call.
The example below calls Create Credit or Transfer Transaction API, moving funds from one user's wallet to another. A user tapping "send" in your app is the clearest case for the context headers: the action is theirs, so all three describe their session, not your backend. The source user is identified by X-Auth-User-ID and the recipient by the email in the payload. X-Auth-User-ID is an existing requirement of this endpoint and is not a context header; it names the account the call acts on, while X-Auth-User-IP describes the network the person acted from.
Create Credit or Transfer Transaction request
curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/funds' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--header 'X-Auth-Actor: end-user' \
--header 'X-Auth-User-IP: 203.0.113.42' \
--header 'X-Auth-Device-ID: c3f2a1b0-6d4e-4a19-9f83-71b2c0d5e8a7' \
--header 'X-Auth-User-Agent: PartnerPay/4.2.1 (iOS 17.5; iPhone15,3; build:4210)' \
--data-urlencode 'email=john.doe@example.com' \
--data-urlencode 'amount=50'
Create Credit or Transfer Transaction response
{
"id": "edde2e3c44428660970d11e0b53888b9c3de744c82a3568c70c6f5c8c0023e98",
"ref_id": "000002C1000000000003000000000278",
"user_id": "cb532825ef5397a0571b3b66f20780d7",
"wallet_id": "4cc5efa24dc483f578dcccc17ac6b459",
"confirm": "skip",
"sor_transaction": null,
"category_details": [
{
"name": "DEFAULT",
"amount": "50.00",
"currency": "USD"
}
]
}
The response body is the endpoint's normal response. Context headers add nothing to a successful response.
Where no end user is behind the call, send the actor header alone. The example below calls Get Program Credit (Partner) Prefund, which returns the outstanding balance of the partner pool account. No customer is involved, so the actor is operator or system.
Get Program Credit (Partner) Prefund request
curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/prefund/credit' \
--header 'Authorization: ••••••' \
--header 'X-Auth-Actor: system; id=treasury-monitor-prod-0001'
Get Program Credit (Partner) Prefund response
{
"balance": "91224459.010000"
}
7. Handle rejections
Once enforcement is in effect, a header that fails validation returns 400 Bad Request with the standard MatchMove error object, where code identifies the failing condition and source names the header that failed. Handle it as you would any other 400 from the platform. See Handle endpoint errors for the object and the general handling rules.
Treat every rejection as an integration defect, not a transient failure. The request was not processed. Fix the value and resubmit; retrying it unchanged returns the same error.
Degraded values are different. A private IP or a leaked HTTP library user agent is accepted and carries no code, so the request goes through and nothing in the response tells you. These appear in your weekly coverage report instead. Treat any non-zero rate on a production end-user endpoint as a defect to fix before enforcement.
Conformance tests
Run these before go-live. Each has one correct outcome. Run the device identifier tests again after any change to your client storage layer.
Device identifier
- Force-quit and relaunch the app. Identical value.
- Reboot the device. Identical value.
- Log out, then log in as a different user. Identical value.
- iOS: delete and reinstall the app. Identical value.
- Android: delete and reinstall the app. New value.
- Back up, then restore onto a second device. New value on the second device.
- Install on two devices for the same user. Two distinct values.
- Web: clear site data. New value.
- Cold start with 20 concurrent accessor calls. One value.
- Inspect a sample of production values. All match
^[A-Za-z0-9_-]{16,128}$, no duplicates beyond genuine shared devices.
The restore-to-a-second-device test is the one partners most often fail, and the most damaging. A cloned identifier makes two physical devices indistinguishable, so a handset the user never enrolled looks familiar and never triggers a step-up, the extra authentication challenge raised when an action looks unusual.
User agent
- Browser request through your full edge and proxy chain. Value matches what the browser sent, byte for byte.
- Native app. Matches the product token format, and contains no user-assigned device name.
- Hybrid webview. Webview string present with your app token appended.
- Agent-assisted transaction. Carries
channel:agent-assisted, never a browser string. - Inspect a sample of production values. No HTTP library signatures, email addresses, or phone numbers.
- Cross-check against device identifier platform history. No identifier appears as both iOS and Android.
The last two catch the most common defects: a backend leaking its own HTTP client string, and a cross-platform build hardcoding one platform token.
Actor
- Every automated job sends
systemwith a distinctid; every back-office action sendsoperatorwith an opaqueid, and no context headers. - Every end-user call sends
end-userand all three context headers. Every program or configuration call sendsoperatororsystem. - Inspect one day of your outbound requests.
X-Auth-Actornever readsend-userfor traffic that originated from a job, and never readssystemoroperatorfor traffic that originated from your app or website.
Common questions
Many of our users share one IP, behind corporate NAT or a VPN. Send the IP you observe. Shared ranges, VPNs, and proxies are handled in scoring.
We proxy all mobile traffic through one egress gateway and cannot see the device IP. You cannot meet the requirement on that path. Raise it with your technical account manager before enforcement.
Our users share devices (family accounts, kiosks, agent-assisted onboarding). Send the same identifier for each. MatchMove models many-to-many relationships between devices and users. Tell your risk contact about kiosk and agent devices so they are classified rather than flagged.
The identifier resets when a web user clears cookies. That reduces signal on the web channel, and it is correct. Do not compensate with fingerprinting without discussing it with MatchMove first.
We already send a device identifier to our own fraud vendor. Can we reuse it? Yes, if it meets the format rules and is not from a prohibited source. Reusing one value keeps your risk view and MatchMove's aligned.
What if a device identifier is spoofed? It is a signal, not an authentication factor. Compromise is contained by revoking the device's binding to the user, so it is no longer treated as known, and by challenging the action with step-up authentication. Rotating the identifier is not the remedy.
Can we normalize the user agent before sending? No. Send it verbatim. Parsing happens on MatchMove's side. A normalized string breaks the 3DS browser channel and defeats bot detection, which depends on exact token order and spacing.
Rollout
These headers roll out in two phases. During the warning phase, missing or degraded values are accepted and the request is processed, and MatchMove will share with you details of your compliance on a periodic basis.
Once enforcement begins, a missing or invalid header on an end-user request is rejected. The dates for each phase, per header, are stated in the release notes.
On this page
- Capture request context headers