Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

RyzeAPI uses two types of token to authenticate each request. Both are sent in the token header. Understand when to use each one and how to handle the most common errors.

​
Two types of token

TokenAccount

This is your main token. With it you create and administer your WhatsApp instances.Scope: your entire account, all of the instances it owns.When to use: create an instance, list all of your instances, delete an instance, or any operation in which you need to act as the “account owner”.

TokenInstance

Generated automatically when you create a new instance. Each instance has its own.Scope: only that specific instance.When to use: day-to-day operations, send a message, create a group, configure a webhook, read contacts, etc. It is the token you will use in 99% of calls.
As a rule of thumb: use the TokenInstance whenever the endpoint has :instance in the path. Use the TokenAccount only to create/list/delete instances.

​
Token lifecycle

1

You receive your TokenAccount

Delivered when your account is created. Store it in a safe place, it cannot be recovered later.
2

Create an instance

Call POST /api/instance/new sending your TokenAccount. The response includes the data.token field, which is the TokenInstance for that instance.
3

Use the TokenInstance day to day

From there on, every operation on that instance (sending a message, reading contacts, configuring a webhook) uses the TokenInstance.
4

Need to create another instance?

Go back to using your TokenAccount to provision one more.

​
Three ways to send the token

We recommend always using the token header. The other forms exist only for specific cases. 
POST /api/message/text/$Instance_Name HTTP/1.1
Host: ryzeapi.cloud
Content-Type: application/json
token: your-token-here

{"number": "5511999999999", "message": "Hello!"}

​
Authorization: Bearer header (compatibility)

In case your tool only supports the Bearer standard. 
Authorization: Bearer your-token-here

​
?token= query string (browser WebSocket only)

Used when it is not possible to send headers, the typical case being WebSocket in browser JavaScript, since new WebSocket(...) does not accept custom headers. 
const ws = new WebSocket(
  `wss://ryzeapi.cloud/ws/$Instance_Name?token=${instanceToken}`
);
Query strings appear in proxy and CDN logs. Do not use in production outside the WebSocket/browser case.

​
Who can do what

  • Any :instance endpoint of the instance itself: send a message, read contacts, configure a webhook, create a group, etc.
  • Inspect the current state of the instance itself (GET /api/instance/list)
  • Open a WebSocket connection to receive events in real time
  • TokenInstance does not create new instances, use TokenAccount for that
  • The TokenInstance of one instance does not operate another instance, each token is only valid for its own
  • The TokenAccount/TokenInstance of one account does not operate instances of another account

​
Access protection (ownership)

RyzeAPI automatically checks, before each operation, whether the token sent has permission for that specific resource. This prevents a token from leaking access to third-party instances. Examples of what is automatically blocked:
  • Trying to send a message on instance B using the token of instance A → 403
  • Trying to delete an instance that belongs to another account → 403
  • TokenAccount trying to create more instances than its quota allows → 403

​
Authentication errors

All auth error responses come with HTTP 401 (invalid token) or 403 (no permission) and follow the format: 
{
  "success": false,
  "error": {
    "message": "human-readable description of the problem"
  }
}

​
Messages you may encounter

HTTPMessageMost likely cause
401Missing token in headerYou did not send the token header
401Missing token in header, Authorization header, or query parameterNone of the 3 token forms were used
401Invalid tokenToken does not exist, is wrong, or has been revoked
401Invalid instance tokenThe token does not match the instance in the path
403Instance token does not match requested instanceYou are using the TokenInstance of A on the path :instance=B
403Instance does not belong to your accountTokenAccount trying to operate an instance of another account
403Account instance quota exceededYou hit the instance limit for your account
If you receive Invalid token without knowing why, check: (1) that the token is complete and has no spaces; (2) that you are using the right type of token for that endpoint; (3) that the instance exists and is active.

​
Security: best practices

Treat every token as a credential, store it in environment variables or a secrets vault, never in the frontend or in public repositories.
Use one TokenInstance per instance, if one leaks, you only revoke that one.
Use HTTPS in production, RyzeAPI accepts only secure connections.
Use the token header (not the query string) in most cases, headers do not end up in proxy logs.
Monitor the X-RateLimit-Remaining header to avoid being blocked for excess requests.

​
Next

Error types

The response formats and how to interpret each HTTP code.

Rate limit

How much you can call per minute and how to react to 429.