JWT verification
The Sutro API verifies JWTs that your system generates and includes in requests from your Builders.Required claims
Every JWT must include the following claims:| Claim | Description |
|---|---|
sub | The security ID (SID) associated with the user in your system |
iss | The issuer SID previously registered with the UAPI |
aud | Must include https://sapi.withsutro.com |
Configuration
Two elements are needed for JWT verification:- Register an Issuer SID
- Register a Verification Certificate
1. Register an issuer SID
Issuer SIDs identify and verify the source of JWTs.- Each SID must be globally unique and comply with RFC 7519.
- In practice, use a UUID or a URI containing a domain you own.
- Multiple issuer SIDs can be registered if needed.
2. Register a verification certificate
JWTs signed with RS256 require a matching public certificate to be registered with the UAPI. Once registered, that certificate can be linked to one or more issuer SIDs.You hold the private key; Sutro never stores it. Register only the public certificate.
mTLS security
Mutual TLS (mTLS) adds another layer of authentication, requiring clients to present a certificate for every request. This uses public-private key pairs: the client signs each request with its private key, and Sutro verifies it using the corresponding public certificate registered via the UAPI.Configuration
Sutro can generate mTLS certificates for you.- Certificates are signed by Sutro’s private Certificate Authority.
- The public certificate is stored by Sutro; the private key is available only once at generation.
- Certificates expire after 90 days.
Automatic renewal of mTLS certificates will be available in an upcoming release.
Summary
| Security Layer | What You Do | Managed In |
|---|---|---|
| JWT Verification | Register issuer SID and verification certificate | UAPI |
| mTLS Security | Upload or generate client certificate | UAPI |
| Certificate Renewal | Manual (auto-renew coming soon) | UAPI |