Authentication

The Gesvision API uses JWT (JSON Web Tokens) for authentication. Every API request must include a valid token in the Authorization header.

Obtaining a token

Send a POST request to the authentication endpoint with your Gesvision credentials:

curl -X POST https://app.gesvision.com/Gesvision/rest/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_api_user",
    "password": "your_api_password"
  }'

A successful response returns the JWT token and its expiration:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400
}

Field	Type	Description
token	string	The JWT token to use in subsequent requests
expiresIn	integer	Token lifetime in seconds (typically 24 hours)

Using the token

Include the token in every API request as a Bearer token:

curl https://app.gesvision.com/Gesvision/rest/api/v1/invoices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token expiration and renewal

• Tokens expire after the period indicated by expiresIn (in seconds)
• When a token expires, the API returns 401 Unauthorized
• Simply request a new token by calling the login endpoint again
• There is no refresh token mechanism — re-authenticate with your credentials

Permissions

The API respects the same permission model as the Gesvision web application. Your API user inherits the roles and access rights configured in Gesvision Administration → Users & Roles.

Permission	What it controls
Read invoices	GET /api/v1/invoices and GET /api/v1/invoices/{id}
Write invoices	POST, PUT, DELETE on invoices
Read orders	GET /api/v1/orders
Write orders	POST, PUT, DELETE on orders
Payments	POST /api/v1/payments
Customers	GET and PUT on customers

Security best practices

• Never expose tokens in URLs, query parameters, or client-side code
• Store tokens in environment variables or a secrets manager
• Use a dedicated API user — do not share your personal Gesvision login
• Rotate credentials periodically
• The API enforces HTTPS — plain HTTP connections are rejected
• Tokens are signed with HMAC-SHA256 and cannot be forged or modified