Skip to main content

JWS Authentication

EBANX uses JWS (JSON Web Signature) based on RFC 7515 to authenticate API requests across all products, including Payments, Payouts, and Transfers. Every server-to-server request to the EBANX API must include a cryptographic signature in the X-JWS-Signature HTTP header. This signature proves your identity and guarantees the integrity of the request payload.

Why JWS authentication​

JWS authentication provides significant security advantages over traditional API key authentication:

  • Private key isolation — Your private key never leaves your infrastructure. Only the public key is shared with EBANX.
  • Request integrity — Each request is cryptographically signed, making it impossible to tamper with the request body without invalidating the signature.
  • Non-repudiation — The origin of each request can be verified, providing an audit trail.
  • No shared secrets in transit — Unlike integration_key, no secret is transmitted with each request.

How it works​

JWS authentication uses asymmetric cryptography (public/private key pair). You sign each request with your private key, and EBANX verifies the signature using your registered public key.

  1. Merchant builds the JSON request body.
  2. Merchant signs the payload with their private key using RS256.
  3. Merchant sends the request to the EBANX API with the X-JWS-Signature header.
  4. EBANX API looks up the merchant's public key using the kid from the JWS header.
  5. EBANX API verifies the signature against the request body.
  6. EBANX API returns the authenticated response.

EBANX uses the detached payload variant of JWS compact serialization (RFC 7515 — Appendix F). This means the request body is used to compute the signature but is not embedded inside the JWS token itself. The token format is:

BASE64URL(header)..BASE64URL(signature)

The middle section (payload) is intentionally left empty because the actual payload is the HTTP request body sent alongside the token.

Technical specifications​

Supported algorithms​

AlgorithmStandardKey sizeDescription
RS256RSASSA-PKCS1-v1_5 with SHA-2564096-bit minimumThe only supported algorithm for merchant-facing JWS authentication

JWS header fields​

Every JWS token must include the following protected header fields:

FieldTypeRequiredDescription
algstringYesMust be RS256
kidstringYesYour unique Key ID, provided by EBANX after public key registration
b64booleanRecommendedSet to false to indicate the payload is not base64url-encoded (RFC 7797). When present, the crit header must also be included and must contain "b64"
critstring[]ConditionalRequired when b64 is set. Must contain ["b64"] to signal that b64 is a critical header that must be understood

Requirements​

  • RSA key pair — RSA 4096-bit minimum. You generate the key pair and keep the private key secure.
  • Registered public key — Your public key must be registered with EBANX before you can authenticate. Contact your EBANX Integration Specialist.
  • Key ID (kid) — After registration, EBANX provides a unique kid that identifies your public key. This value is included in every JWS header.

Key rotation​

When you need to rotate your keys (recommended periodically or if a key is compromised):

  1. Generate a new RSA key pair.
  2. Send the new public key to your EBANX Integration Specialist.
  3. Receive a new kid for the new key.
  4. Update your signing implementation to use the new private key and kid.
  5. Confirm with your Integration Specialist that the old key can be deactivated.
Zero-downtime rotation

EBANX supports multiple active keys per merchant. During rotation, both the old and new keys can be active simultaneously, allowing you to transition without downtime.

Getting started​

To start using JWS authentication, see the Integration Guide for step-by-step setup instructions and code examples.

If you are currently using the legacy integration_key authentication method, refer to the Migration Guide for instructions on transitioning to JWS.

FAQ​

Can I use the same key pair for sandbox and production?
You can, but it is recommended to use separate key pairs for each environment to minimize risk.

What happens if my private key is compromised?
Contact your EBANX Integration Specialist immediately to deactivate the compromised key and register a new one.

Do I need to sign GET requests?
GET requests without an HTTP body can also be authenticated via JWS. The signature computation takes the body into account, but it is perfectly valid to sign and authenticate requests that do not have one. Contact your Integration Specialist for guidance on your specific integration.

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: