API References

API Essentials

Core concepts and essential information about the SAVA BaaS API.

The partner JWT

Every call you make is authorized by the JWT that SAVA issues for your partner account. How it's issued is covered in Authentication; you never need to parse it in your integration, but two claims in its decoded payload are worth knowing about:

Decoded payload
{
  "jti": "HYILNHJ5TAILSLXYSWXMGFLEOGQVIXPW4VXJAO2WSSWQBDPTDJHQ",
  "iat": 1741272289,
  "iss": "ABPMW6SJ6SBPR5OEAIZGANDBNLMOOOBMTTLVIACABYAMTU5SUYY6UY2R",
  "name": "partner-bridgelabs",
  "sub": "UA5SKV2KRSYTHK3Q36T6F5YYGVQXRKZWJZPBNY6RDP7BL7IMKIIBNOAQ",
  "nats": {
    "pub": {},
    "sub": {},
    "issuer_account": "AAQLOMWDVSG4A53KHIUX6UMXPAQYWAK3POMVIN4I7NHWVXOLZTI7N6WO",
    "tags": [
      "partner:52c844f1-17b3-4aa5-9a59-f4f7eaca22c3"
    ],
    "type": "user",
    "version": 2
  }
}
  • nats.tags carries partner:<partner_id>. That UUID is your partner ID, the one you substitute into every request subject (svc.<service>.<partner_id>.<operation>).
  • name and sub identify your partner user on the platform. SAVA support may ask for them when tracing an issue.

Using the JWT

Our service endpoints require the JWT to be passed as a token header on each NATS request message. This is separate from the connection credentials, since NATS does not forward connection credentials to service handlers automatically.

The generated service clients that SAVA provides set this header for you. If you're making raw NATS requests, set it yourself:

import { headers } from "nats.ws";
 
// Raw NATS request with the JWT in the token header
const h = headers();
h.set("token", "<your_jwt_token>");
 
const response = await nc.request(
  "svc.entity.<partner_id>.create",       // request subject (see pattern below)
  JSON.stringify(payload),
  { headers: h, timeout: 10_000 }
);
 
const result = JSON.parse(new TextDecoder().decode(response.data));

Request subject pattern

All API requests use NATS subjects with the following structure:

svc.<service>.<partner_id>.<operation>

Components:

  • svc: Service prefix (constant for all API calls)
  • <service>: Target service name (e.g., account, card, entity, user)
  • <partner_id>: Your partner's unique identifier (UUID format)
  • <operation>: The specific operation to invoke

Examples:

svc.entity.550e8400-e29b-41d4-a716-446655440000.create
svc.account.550e8400-e29b-41d4-a716-446655440000.get_balance
svc.card.550e8400-e29b-41d4-a716-446655440000.issue
svc.user.550e8400-e29b-41d4-a716-446655440000.list

The partner_id in the subject scopes all operations to your partner account, ensuring data isolation and partner-specific routing.

Formats

  • Dates: All dates are formatted in RFC 3339 unless otherwise stated. This format is mostly interchangeable with ISO8601 format
  • Monetary values: in requests are expected to be an integer in cents, however responses will provide a string representation which includes the currency symbol.
  • Phone numbers: all phone numbers are expected to include the country code unless otherwise expected (eg. 27763456789)

Errors

Failed requests reply with a JSON error envelope:

Error envelope
{
  "error": {
    "code": 400,
    "message": "missing documents"
  }
}
FieldTypeDescription
error.codenumberHTTP-style status code: 400 invalid or incomplete request, 403 permission denied, 404 resource not found, 500 unexpected server error
error.messagestringHuman-readable reason, useful for logs and debugging

Each endpoint's Possible Errors section lists the specific failures it can return. Two things to handle on top of the envelope:

  • Timeouts: NATS request-reply calls time out if no responder answers (the client's default is often just a few seconds). Set an explicit timeout and treat it as retryable.
  • Idempotency: money-moving endpoints accept a clientTxId so a retried request isn't processed twice. Always send one where the reference documents it.

Document uploads

Document upload conventions (bucket names, file naming, submission) are specific to the verification flows and documented where they're used: see KYB: Uploading Documents for business verification and KYC: Document Upload for user verification.

On this page