Skip to main content

​
Overview

Our security model relies on two complementary mechanisms: mutual TLS (mTLS) and JSON Web Tokens (JWTs). mTLS ensures that only trusted servers can call our APIs. JWTs ensure that only authorized users (which we call Builders) can access the resources they are allowed to use. To understand why both are needed, this document explains the three core security processes—Identification, Authentication, and Authorization—and how mTLS and JWTs each address different parts of them.

​
Security Processes

When deciding whether a request should be executed, three steps are involved:
  1. Identification — “Who is making this request?”
  2. Authentication — “Can they prove it?”
  3. Authorization — “Are they allowed to do this?”

​
Identification

Identification is the act of claiming an identity. This could be a username, an API key, a certificate, or any identifier that asserts who or what is making a request.
Identities can represent individual users (“I am Sam Jones”), systems, or roles (“I have the FinancialAnalyst role”).

​
Authentication

Authentication is the evidence that supports an identity claim.
Examples include passwords, private keys, API secrets, or any secret that only the true identity holder should possess.

​
Authorization

Authorization determines whether the authenticated identity has permission to perform the requested action.
This permission information may be stored on the server or embedded directly within a request (as with JWT claims).

​
JWTs

JSON Web Tokens (JWTs) are compact, signed tokens that carry identification and authorization information. A JWT contains three parts:
  • Header — how the token is constructed
  • Payload — identity and other claims
  • Signature — proof that the token is genuine
Within the payload, the subject (sub) claim identifies the user or entity: 
{
  "sub": "123-45-6789"
}
This value is a Security Identifier (SID) that uniquely represents an identity.

​
Signing and Verification

JWTs are signed so that recipients can verify they have not been tampered with. Verification is done by checking that the signature matches the payload using a corresponding verification key.

​
Symmetric vs Asymmetric Keys

JWTs can be signed using:
  • Symmetric keys — one shared key used for both signing and verifying
  • Asymmetric keys — a private key for signing and a public key for verification
Symmetric keys create risk: anyone who can verify a token can also forge one.
Asymmetric keys avoid this. The signing private key never leaves your control, and we only receive the public verification key.

​
Mutual TLS (mTLS)

TLS (formerly SSL) is the standard protocol for verifying a server’s identity and encrypting communication.
In traditional TLS:
  • The server sends its certificate.
  • The client verifies it against a trusted Certificate Authority (CA).
  • The client then trusts that the server is genuine.
mTLS extends this by requiring both sides to present certificates. With mTLS:
  • The client sends its own certificate, signed by a trusted CA.
  • The server verifies this certificate and checks that the client controls the private key associated with it.
This provides strong, cryptographic proof that the request is coming from a trusted system.

​
How the techniques are applied

Sutro relies on mTLS for all server-to-server communication and JWTs for all user-level access control.

​
Why mTLS?

Servers that can call our APIs operate with high privilege.
mTLS ensures that:
  • Only systems you explicitly trust can connect to us.
  • Each client environment can have its own certificate, improving auditability.
  • Private keys stay entirely under your control; we never see them.
This approach supports a Zero Trust Architecture (ZTA), where no system is implicitly trusted and every request must be identified, authenticated, and authorized.

​
Why Asymmetric Keys and JWTs?

While mTLS proves which server is sending a request, it does not tell us which user the server is acting on behalf of.
JWTs fill this gap by conveying identity and permission information for individual Builders. Asymmetric JWT verification is used because:
  • You keep the private signing key, maintaining full control over user management.
  • Sutro only needs the public key, ensuring verification is possible without ever being able to forge tokens.
  • Each authentication service or environment can have its own key pair, making token origin traceable.
This separation—mTLS for server identity, JWTs for user identity—provides strong, flexible, and auditable security.