Skip to main content

​
Overview

VZaps uses more than one authentication mechanism; each endpoint only requires what that flow needs.

​
JWT for integrators (public API)

To obtain a JWT without sending email and password to an integration route, call POST /token with your account client_token and client_secret (managed under Security in the app). The response uses the same access_token and expires_in shape as session-based flows. This endpoint does not use Turnstile.
HeaderWhen to useNotes
Authorization: Bearer <jwt>Instance creation, listing, billing, and owner access to the instanceObtain via POST /token or the web app; required on PUT /instances/create, POST /instances/list, POST /instances/{id}/subscribe, POST /instances/{id}/resume-subscription, and PUT/DELETE /instances/{id}/cancel
X-Client-TokenServer-to-server integrations and token-authenticated callsMust belong to the instance owner
X-Instance-TokenInstance endpoints without JWTReturned in the create-instance response

​
Practical rules

​
Instance and billing

  • Send JWT in the Authorization header.
  • Do not use the instance token as a substitute on these endpoints.

​
List instances

Use POST /instances/list with Authorization: Bearer <JWT> and pagination/filter body fields (page, size, filter, sort, sortDesc). This flow always assumes JWT. 
curl -X POST "https://api.vzaps.com/instances/list" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"size":20,"filter":{},"sort":"createdAt","sortDesc":true}'

​
Instance (session, chat, webhook, and more)

You can use either:
  1. Owner JWT for the instance.
  2. X-Instance-Token together with X-Client-Token.
The API validates the instance and the owner X-Client-Token before processing the request.

​
Example with JWT

curl -X GET "https://api.vzaps.com/instances/INSTANCE_ID/session/status" \
  -H "Authorization: Bearer YOUR_JWT"

​
Example with instance tokens

curl -X GET "https://api.vzaps.com/instances/INSTANCE_ID/session/status" \
  -H "X-Instance-Token: INSTANCE_TOKEN" \
  -H "X-Client-Token: YOUR_CLIENT_TOKEN"

​
Best practices

  • Do not expose X-Client-Token and X-Instance-Token in public front-end apps.
  • Separate credentials per environment.
  • Store the instance token from PUT /instances/create right after creation.
  • On Forbidden, first verify the instance belongs to the user or the X-Client-Token you sent.