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
- Generate NKEY pair locally with
- 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:
Language-Specific Notes
- Node.js: Two options available:
credsAuthenticator(reads the .creds file) orjwtAuthenticator(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:
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
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
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.