Getting Started

Learn how to get started with the SAVA BaaS API.

1. Prerequisites

Before connecting to the SAVA BaaS API, ensure you have:

  • NATS Credentials File (.creds): Contains your NATS JWT from SAVA and your locally generated seed. Follow the Authentication documentation to:
    • Generate NKEY pair locally with nsc generate nkey -u
    • Share your public key with SAVA
    • Receive NATS JWT from SAVA
    • Create your .creds file
  • NATS Client: Install a NATS client library for your programming language. NATS supports various languages, including JavaScript, Python, Go, Java, and more.

Key Point

The SAVA BaaS API uses a single JWT: the one in your .creds file. It's used in two places: it authenticates your NATS connection, and the same JWT must be re-presented as a token header on every request you send (see Using the JWT). There is no separate API key or second token to manage.


2. Connecting to the SAVA BaaS API

2.1 Connection URLs

To connect to the SAVA BaaS API, you'll need to use the following NATS URL:

  • Public URL: wss://hermes.sava.africa

This URL is sufficient for establishing a connection to the SAVA BaaS API.

2.2 Basic Connection Steps

The connection method varies by programming language. Choose the appropriate example below:

import { connect, credsAuthenticator } from "nats.ws";
import * as fs from "fs";
 
// Read the entire .creds file
const credsContent = fs.readFileSync("/path/to/your.creds", "utf-8");
 
// Connect with credsAuthenticator (automatically extracts JWT and seed)
const nc = await connect({
  servers: ["wss://hermes.sava.africa"],
  authenticator: credsAuthenticator(new TextEncoder().encode(credsContent))
});
 
console.log("✓ Connected to SAVA BaaS API");

Language-Specific Notes

  • Node.js: Two options available: credsAuthenticator (reads the .creds file) or jwtAuthenticator (uses the JWT and seed directly)
  • Python, Go, Java, C#: Can directly use the .creds file path

3. Making Your First Request

Every endpoint on the platform is a plain NATS request-reply call: send JSON to a subject (svc.<service>.<partner_id>.<operation>) with your JWT in the token header, and you get JSON back. Because the transport is that simple, there are two equally supported ways to integrate. Both are first-class, and you can mix them freely in the same codebase.

Option A: Generated clients. SAVA provides generated service clients (*.gen files) during onboarding, one per service (entity, account, card, and so on). They wrap the request-reply calls, set the token header for you, and give you typed methods like entityService.create(...). Every generated service takes the same three constructor parameters:

new EntityService(connection, jwt, [partnerId])

Option B: Raw NATS requests. Use the NATS client library you already connected with, and nothing else: build the subject, attach the token header, send JSON. See the request subject pattern and Using the JWT in API Essentials for the two conventions involved.

Complete Example

The same flow implemented both ways: connect, create a business entity, then list entities. Pick whichever matches your integration and use it as a reference.

Option A: With the generated client

Complete example
import { connect, jwtAuthenticator } from "nats.ws";
import { EntityService } from "./entity.gen"; // Generated service
 
async function main() {
  // Step 1: Configuration with JWT and seed
  const config = {
    jwt: "eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5LW5rZXkifQ...",
    seed: "SUAETLJPP53NULSKWUBHKIKK2HVYGZW43NMMIPKNFXIFJXZWSHIT2QOYXI",
    partnerId: "your-partner-id"
  };
 
  // Step 2: Connect to SAVA BaaS API
  const nc = await connect({
    servers: ["wss://hermes.sava.africa"],
    authenticator: jwtAuthenticator(
      config.jwt,
      new TextEncoder().encode(config.seed)
    )
  });
 
  // Step 3: Initialize EntityService with JWT
  const entityService = new EntityService(
    nc,            // NatsConnection
    config.jwt,    // JWT token (sets header: token)
    [config.partnerId] // Partner ID as array
  );
 
  // Step 4: Create an entity
  const newEntity = await entityService.create({
    name: "Acme Corporation",
    trading_name: "Acme Corp",
    registration_number: "202012345607",
    email: "contact@acmecorp.com",
    country: "ZAF",
    entity_type: "business",
    tax_number: "9876543210"
  });
 
  console.log("✓ Entity created:", newEntity);
 
  // List all entities
  const entities = await entityService.list_entities({});
  console.log("✓ Total entities:", entities.entities.length);
 
  // Clean up
  await nc.close();
}
 
main().catch(console.error);

Names may differ per language

Method and type names follow each language's conventions in the generated clients (for example list_entities in JavaScript, listEntities in Java, ListEntitiesAsync in C#). Check the generated files you received for the exact signatures.

Option B: With raw NATS requests

Complete example
import { connect, jwtAuthenticator, headers } from "nats.ws";
 
async function main() {
  // Step 1: Configuration with JWT and seed
  const config = {
    jwt: "eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5LW5rZXkifQ...",
    seed: "SUAETLJPP53NULSKWUBHKIKK2HVYGZW43NMMIPKNFXIFJXZWSHIT2QOYXI",
    partnerId: "your-partner-id"
  };
 
  // Step 2: Connect to SAVA BaaS API
  const nc = await connect({
    servers: ["wss://hermes.sava.africa"],
    authenticator: jwtAuthenticator(
      config.jwt,
      new TextEncoder().encode(config.seed)
    )
  });
 
  // Step 3: Every request carries the JWT as a token header
  const h = headers();
  h.set("token", config.jwt);
 
  // Step 4: Create an entity
  const reply = await nc.request(
    `svc.entity.${config.partnerId}.create`,
    JSON.stringify({
      name: "Acme Corporation",
      trading_name: "Acme Corp",
      registration_number: "202012345607",
      email: "contact@acmecorp.com",
      country: "ZAF",
      entity_type: "business",
      tax_number: "9876543210"
    }),
    { headers: h, timeout: 10_000 }
  );
  const newEntity = JSON.parse(new TextDecoder().decode(reply.data));
  console.log("✓ Entity created:", newEntity);
 
  // List all entities
  const listReply = await nc.request(
    `svc.entity.${config.partnerId}.list-entities`,
    JSON.stringify({}),
    { headers: h, timeout: 10_000 }
  );
  const entities = JSON.parse(new TextDecoder().decode(listReply.data));
  console.log("✓ Total entities:", entities.entities.length);
 
  // Clean up
  await nc.close();
}
 
main().catch(console.error);

Remember to handle connection errors and implement reconnection logic as needed for production environments.

For more detailed information on using specific API endpoints, please refer to the individual service documentation sections.

On this page