API Authentication

API authentication is a necessary part of managing the security of your REST API-enabled applications.

Access to the API is granted by adding a valid access token to your requests.

🚧

Warning

The token must be kept secret and not revealed to anyone. If a token is compromised, you need to reset it immediately.

Access Token prerequisites

Before you can retrieve the Access Token, you need the following:

• Marosa API credentials
• OAuth2 credentials

Marosa API credentials

Your account credentials identify you as an authorized Marosa API user. Contact with the Marosa Sales team to establish an account that meets your tax needs. Learn More

OAuth credentials

After your Marosa API account is created, you will receive your own client ID and client secret, which identifies you as an authorized OAuth2 user.

Access Token

The combination of your Marosa API credentials and your OAuth2 credentials are used to request an Access Token that allows you to access the REST API.

Retrieving an Access Token

Each call to the REST API requires a valid Access Token.

📘

Note

One Access Token can be used numerous times within its lifetime. Refer to Using an Access Token for more details.

To obtain an Access Token, send a request using a POST method to the following token endpoint URL:

https://gw.vatify.es/api/invoicing/auth

Specifying the following parameters in the request's body:

{
  "username": "marosa",
  "password": "password",
  "client_id": "1234asdf",  
  "grant_type": "password"  
  "client_secret": "12345678asdfqwer",  
}

🚧

Warning

The client_id and client_secret parameters are issued for each integration against the REST API. They are confidential values and should not be exposed to any users of the integration.

The response from the call to the token endpoint is a JSON object.

Success response

If an error occurs, the JSON object has one “error” property with a message that describes the reason for failure, for example:

{
    "timestamp": "2025-05-14T17:37:43.107+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "path": "/api/auth"
}

Using Access Token

When an Access Token is successfully retrieved, the returned JSON object has multiple properties. The expires_in property defines how many seconds after the token is issued that the Access Token is valid. This token must be added to the HTTP header to validate/authorize further REST API calls.

📘

Note

Best practices recommends an Access Token be used for most of its lifetime.

Use the expires_in property and the response time of the authorization request to determine if a new token is needed. Requesting a new Access Token for each REST API request is not an acceptable practice because it reduces processing rates and increases processing times. Failure to reuse Access Tokens properly can cause rate limits on authorization requests to be exceeded.

Authenticating requests

All API requests against the REST API endpoints must be made over HTTPS. When making a request, set the Access Token in the ‘Authorization’ header of the request with the token type and Access Token, for example:

Authorization: Bearer {ACCESS_TOKEN}

Or, using the above response as an example:

Authorization: Bearer "valid_token_ID"

Note: For example purposes.

For additional assistance or technical support, contact the Marosa team directly.