Authentication

The Mozarto Cashier API authenticates requests using a company JWT issued by the Mozarto back office.

Required headers

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

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

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	Required	Description
`userId`	string	Yes	Your internal user identifier
`email`	string	Yes	User's email address
`firstName`	string	Yes	User's first name
`lastName`	string	Yes	User's last name
`phone`	string	Yes	User's phone number
`countryCode`	string	Yes	ISO country code (e.g. `"GB"`, `"DE"`)
`emailVerified`	string	No	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 company JWT

Your company 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.

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 company.

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
`COMPANY_TOKEN`	Your company JWT 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 {{COMPANY_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 company 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 company JWT#

Example request#

Errors#

Security#