Authentication and tenancy

Every request to Samva's email API answers two questions before anything else happens: who is asking, and whose data are they allowed to touch. Authentication answers the first. Tenancy answers the second. They are separate concerns, and understanding where the line falls between them explains a lot of how the product is shaped.

This page is about the model, not the mechanics. For the exact headers, key formats, and signature steps, see the authentication reference.

Two audiences, two methods

Samva authenticates two very different kinds of caller, and it uses a different method for each.

API keys authenticate your code. When your backend sends an email, there is no human present to type a password and no browser to hold a session — there is a server process that needs to prove it is allowed to act on your organization's behalf. An API key is exactly that: a long-lived bearer credential your server presents on every request. It is the right tool for server-to-server work precisely because it carries no notion of a user. It represents the organization, not a person.

Better Auth authenticates people. The Samva dashboard is used by humans signing in, so it relies on sign-in sessions backed by browser cookies — the things you want when a person is at the keyboard and you care about login flows, session expiry, and account recovery.

The reason for two methods is that the two audiences have opposite requirements. A server credential should be stable, long-lived, and storable in a secrets manager; a human session should be short-lived, revocable, and tied to a browser. Trying to serve both with one mechanism forces uncomfortable compromises, so Samva keeps them distinct. As a developer integrating Samva, the credential you reach for is almost always the API key:

import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

The key lives in an environment variable, never in source. That single habit prevents the most common credential leak — a key committed to a repository — which is why every example reads the key from the environment and passes it to the client rather than hardcoding a literal.

The organization is the unit of tenancy

Samva is multi-tenant, and the tenant is the organization. An organization is the boundary that owns everything: verified domains, contacts, conversations, messages, webhooks, and the API keys themselves. When you sign up, you get an organization; when you invite teammates, they join your organization; when you send an email, it is recorded against your organization.

This matters because an API key is not a free-floating secret — it belongs to exactly one organization. That binding is what makes authentication and tenancy collapse into a single step at request time. Samva does not need a separate "which account?" parameter on your calls, because the key already answers it. Present a key, and Samva knows both that the request is legitimate and whose data it is permitted to read or write.

The deeper consequence is an invariant that runs through the entire system: every record is scoped to an organization, and every read is filtered by it. There is no request shape that crosses the tenant boundary. A key issued to one organization cannot list another organization's contacts, fetch another organization's messages, or send from another organization's domain — not because a check happens to be in place on each endpoint, but because tenant scoping is structural. Data is partitioned by organization at the storage layer, and the organization is derived from your credential rather than from anything you pass in. You cannot ask for the wrong tenant's data, because there is no field in which to ask.

This is also why a verified domain is an organization-level asset. The work of authenticating a sending domain — covered in deliverability — is done once per organization, and from then on every key in that organization can send from it. The trust you build attaches to the tenant, not to an individual credential.

Teams and roles

Because the organization owns the data and the credentials, it is also where collaboration lives. You invite teammates into an organization and assign each one a role. Roles exist so that the people who manage billing and members are not necessarily the same people who write integration code or who only need to watch what is happening.

The point of roles is least privilege: a teammate who only needs to read delivery activity should not also be able to rotate the API keys that production depends on. Splitting responsibilities this way limits the blast radius of any single compromised account — a principle that mirrors, at the human level, the same instinct behind scoping keys narrowly at the machine level. Roles and their exact capabilities are managed in the dashboard.

In practice this collaboration happens through invitation rather than shared credentials. From the dashboard you invite a teammate by their email address and assign them a role; they receive an email invitation to join the organization, and from then on they authenticate as themselves with their own session rather than borrowing anyone else's. That is the human-side counterpart to never sharing an API key: each person has a distinct identity and a role that bounds what they can do.

Usage is organization-scoped

Billing follows the same boundary as everything else: usage is metered against the organization, not the individual key. Every send your organization makes is tracked against its allowance, and when an organization exceeds what it is entitled to, the API returns a 402 Payment Required rather than silently sending.

The practical consequence is that cost visibility lives in one place. Every key and every teammate counts against the same organization-level usage, so spend is not fragmented across credentials — there is a single pool to watch and a single limit to manage, regardless of how many keys an organization has issued.

Security posture

Authentication proves who you are; the surrounding security features narrow how and from where that identity can be used, and they verify that traffic claiming to come from Samva actually does.

IP allowlisting

By default an API key works from anywhere it is presented. For organizations that send only from known infrastructure, that is more surface area than necessary — a leaked key is useful to an attacker from any network. IP allowlisting closes that gap by restricting a key's use to a defined set of addresses or ranges. It is defense in depth: the key remains the primary credential, and the allowlist is a second condition that an attacker on an unknown network cannot satisfy even if they hold a valid key. You enable and configure it in the dashboard.

Webhook signatures

Webhooks invert the usual direction of trust. Normally your server authenticates to Samva; with webhooks, Samva calls your endpoint, and now your server is the one that must decide whether to trust the caller. A public webhook URL can be hit by anyone who discovers it, so "this request arrived at my endpoint" is not evidence it came from Samva.

Signatures resolve this. Samva signs each webhook delivery with a shared secret, and your handler recomputes the signature over the received payload and compares. A match proves two things at once: the payload was produced by someone holding the secret (so it is genuinely from Samva), and it was not altered in transit (so the events you act on are the events Samva sent). This is why signature verification is the first thing a webhook handler should do, before parsing or acting on any event. The mechanics of verifying a signature, including the constant-time comparison that avoids leaking information through timing, are covered in Receive webhooks.

Where to go next