Auth and tenancy¶
Callers prove identity differently for each product. Do not assume that one header works everywhere. This page states what an integrator must send to each product.
Fraud Detection¶
The scoring routes use a signed JWT in both directions: your backend signs the calls it makes to the fraud services, and the fraud services sign the calls they make back to your backend.
| What | Contract |
|---|---|
| Header scheme | Authorization: ApiKey <jwt>. The scheme word is ApiKey. A Bearer token is rejected with 401. |
| Token you send (inbound) | RS256, signed with your backend's private key. Required claims: iss=software-service, aud=ai-service and an unexpired exp. |
| Tenant header | x-tenant-id is required on every scoring call; a missing header returns 422. It selects tenant-scoped data (for example blacklists) and is copied onto the resulting report. |
| Routes that require both | POST /call-and-predict (ML scoring), POST /rule_based_engine (rule scoring) and POST /case_management_rule_engine (case-management rules) |
| Token you receive (outbound) | When the fraud service delivers a report to your POST /transaction/create-report, or reads your GET /blacklist/all, it sends Authorization: ApiKey <jwt> signed with the AI service's private key: iss=ai-service, aud=software-service, sub set to the calling service's name, and a short expiry (about 5 minutes). Report delivery also carries x-tenant-id. Your backend must verify these tokens with the AI service's public key. |
| Key exchange and rotation | Each side's public key is configured per environment in advance; nothing is negotiated at runtime. Rotating either key pair needs both sides updated together, or calls fail with 401. |
Errors. A missing header, the wrong scheme, a bad signature, an expired token, or the wrong iss or aud each return 401 with a generic message. Check the scheme word first: it must be ApiKey, not Bearer. See errors, retries and correlation.
Baseline and report pipeline endpoints behind the scoring route are platform-operated event delivery. They are not generic partner interfaces and must not be called directly by integrators.
KYC / KYB¶
| What | Contract |
|---|---|
| Request format | JSON bodies on every route. Files are passed as Cloud Storage HTTPS URLs of the form https://storage.googleapis.com/<bucket>/<object>, not as uploads; face images for ID-photo comparison are base64 strings in JSON. |
| Authentication | The published OpenAPI documents request/response shapes and does not declare a partner security scheme. Production authentication and network exposure are agreed per environment with MasteryHive (for example gateway or private ingress). Confirm before you integrate. |
| Tenancy | There is no tenant header or field. Results are stored and looked up by the userId you send, so use one stable UUID per end customer and never reuse it across customers. Separation between platform customers is agreed with MasteryHive outside the request body. |
| Vendor credentials | Identity, screening, and cloud vendor credentials are held server-side. Integrators never send them. |
| Where to call from | Call from your backend, not from a browser. |
Banking Reconciliation¶
| What | Contract |
|---|---|
| Scope fields | Send tenant_id and partner_id (and branch_id where it applies) in request bodies. They scope which data a session reads and writes. They are scope, not credentials. |
| Correlation | You mint session_id on the ingestion request and it is echoed in the accepted response. Reuse it for status and support queries. |
| Authentication | Reconciliation does not use the Fraud ApiKey JWT scheme on these partner entry points. Production authentication and network exposure are agreed per environment with MasteryHive. |
| Internal mesh auth | How reconciliation services authenticate to each other is not part of the partner contract. |
Exception resolve is scoped by partner_id + tenant_id + domain + cluster_type (+ optional ids / status band). See exception resolve (external).
Integrator checklist¶
- Which product and environment (staging / production)?
- Which auth mechanism does MasteryHive require for that product and environment? For Fraud scoring, send
Authorization: ApiKey <jwt>, notBearer. - Which tenant, partner or user scope fields are required?
- Is the trigger HTTP, asynchronous messaging, or both?
- What is the idempotency or dedupe key on retries?