Authentication

The Mozarto Cashier API authenticates requests using a brand JWT issued by the Mozarto back office. Requests are always made on behalf of a brand - the JWT identifies which brand the transaction belongs to.

Required headers

Every Cashier API request (Pay-In, Pay-Out) must include:

Header	Value	Description
`Authorization`	`Bearer <brand-jwt>`	Your brand JWT - identifies your brand

User context headers

One of the following headers is also required. Which one you send depends on your integration mode:

Header	When to use
`x-user-token`	Send a JWT containing the end user's details. Mozarto decodes it directly and uses the payload (email, first name, last name, etc.) as the user context - no callback to your platform.
`x-user-authorization`	Send the end user's session token from your platform. Mozarto forwards it as the `Authorization` header when calling your configured `User Auth URL` to verify the user server-to-server.

Send x-user-token when your platform issues a signed JWT with the user's details and you want to pass that data to Mozarto without a server-to-server callback. The value must be a valid decodable JWT - passing a plain string causes the request to hang and return a 504 timeout.

Send x-user-authorization when you have a User Auth URL configured in Admin Center - API Credentials and want Mozarto to verify the user against your platform before processing the transaction.

If neither header is present, the request is rejected with 401 Unauthorized.

x-user-token payload structure

Mozarto decodes the JWT and reads the following fields directly from the payload.

Field	Type	Description
`userId`	string	Your internal user identifier
`email`	string	User's email address
`firstName`	string	User's first name
`lastName`	string	User's last name
`phone`	string	User's phone number
`countryCode`	string	ISO country code (e.g. `"GB"`, `"DE"`)
`emailVerified`	string	Verified email address - used for email verification checks

How to create and sign JWT

Example payload:

{
  "userId": "user_123",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+441234567890",
  "countryCode": "GB",
  "emailVerified": "john.doe@example.com"
}

Sign the JWT using the Secret key from Admin Center - API Credentials. This is the same secret Mozarto uses to verify the token on every request.

To generate a test token for development:

Open https://jwt.io

Paste the payload above into the Payload field

Enter your Secret key from Admin Center - API Credentials into the Verify Signature field

Copy the encoded value from the top panel

In production, generate the JWT on your server using your platform's JWT library:

Never hardcode the secret key in client-side code or version control. Store it as an environment variable on your server.

Obtaining your brand JWT

Your brand JWT is generated by Mozarto and is available in the back office:

Admin Center - API Credentials

Copy the Token value from that page and use it as the Authorization: Bearer value on all Cashier API requests. Each brand has its own Token - use the token of the brand you are transacting for.

The token has a long expiry and does not need to be refreshed regularly. If credentials are compromised, request new credentials from or contact the Mozarto support team - reissuing credentials invalidates all previously issued tokens for your brand.

Example request

Store both tokens as environment variables to avoid pasting them into every request. Add the following variables in your HTTP client (Apidog: Environments - Edit, Postman: Environments - Add):

Variable	Value	Used in
`BRAND_TOKEN`	Your brand JWT (`Token`) from Admin Center - API Credentials	`Authorization` header on every request
`USER_TOKEN`	A signed JWT containing the end user's details, signed with your Secret key	`x-user-token` header on every request
`SECRET_KEY`	Your Secret key from Admin Center - API Credentials	Signing `x-user-token` JWTs on your server

Reference them in your request headers:

Authorization: Bearer {{BRAND_TOKEN}}
x-user-token: Bearer {{USER_TOKEN}}

USER_TOKEN must be a valid signed JWT with a non-empty payload. An empty-payload token ({}) passes the format check but provides no user context - Mozarto will not be able to identify the user. The payload must contain the user's details (email, name, etc.) as defined by your platform. Passing a plain string instead of a JWT causes the request to hang and return a 504 timeout.

For curl, export both as shell variables:

Errors

HTTP Status	Meaning
`401 Unauthorized`	Token missing, invalid, or expired
`403 Forbidden`	Password expired - user must change password

Security

Never expose your brand JWT in client-side (browser) code.

All Mozarto API calls must be made from your server.

If credentials are compromised, request new credentials from or contact the Mozarto support team immediately.

3. Authentication

Authentication#

Required headers#

User context headers#

x-user-token payload structure#

How to create and sign JWT#

Obtaining your brand JWT#

Example request#

Errors#

Security#