Documentation/Getting Started

Getting Started

Learn how to get started with the Vertex API

Prerequisites
Connecting to the Vertex API
1. Connection URLs
2. Basic Connection Steps

1. Prerequisites

Before connecting to the Vertex 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 Vertex API uses a single JWT system. The NATS JWT in your .creds file provides complete authentication - no additional tokens or authentication steps are needed.

2. Connecting to the Vertex API

2.1 Connection URLs

To connect to the Vertex 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 Vertex 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 Vertex API");

Language-Specific Notes

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

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.

Authentication Token

When making API calls, you must include your JWT (JSON Web Token) in the request header. The API uses this token to authenticate and authorize your requests.

For NATS requests: Pass the JWT token in the header with the key token.

// Making a request with JWT in header
const response = await makeRequest({
  endpoint: 'svc.card.{partner}.request',
  headers: {
    token: "<your_jwt_token>"  // JWT passed in header
  },
  body: payload
});

Complete Example

Here's a complete, production-ready example showing how to connect and make API calls:

Service Constructor Requirements

All Vertex API codegen services require exactly three parameters:

new EntityService(connection, jwt, [partnerId])

Complete example(javascript)

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 Vertex 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 5: Create an entity
  const newEntity = await entityService.create({
    name: "Acme Corporation",
    trading_name: "Acme Corp",
    registration_number: "2020/123456/07",
    email: "contact@acmecorp.com",
    country: "ZAF",
    entity_type: "business",
    tax_number: "9876543210",
    address: {
      address_line_1: "456 Commerce Road",
      city: "Cape Town",
      state: "Western Cape",
      postcode: "8001"
    }
  });

  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);