API Authentication

All Voice Monkey v3 API requests authenticate with a single token.

Getting your token

1. Sign in to API Tokens in the console.
2. In the Create New Token form, give it a name that identifies where it’ll be used — e.g. Home Assistant, IFTTT, Personal scripts.
3. Click Create Token. The token appears in the list with show/hide and copy controls — copy the value and treat it like a password.

Tip

Create a separate token per integration. If one is ever leaked or you stop using a service, you can revoke just that token without breaking your other integrations.

Caution

Never commit a token to a public repository. Use a secrets manager, environment variable or (for Home Assistant) a secrets.yaml file.

Passing the token

You can send the token in any of three places — pick whichever suits your HTTP client.

1. As a query parameter

POST https://api-v3.voicemonkey.io/trigger?token=YOUR_TOKEN

2. As a JSON body field

{ "token": "YOUR_TOKEN", "device": "DEVICE_ID" }

3. As an Authorization header

Authorization: Bearer YOUR_TOKEN

Rotating or revoking a token

If a token is compromised — or you’ve stopped using the integration it belonged to — go to API Tokens, click Delete on the row, and (if you still need it) click Create Token to mint a replacement. Requests using the deleted token start returning 401 Unauthorized immediately.

Error responses

Status	error body	Meaning
401	UNAUTHORIZED	No token supplied (no ?token=, JSON token, or Authorization header).
401	INVALID_TOKEN	Token doesn’t match any active token on the account.
401	USER_NOT_FOUND	Token exists but isn’t associated with a known user.
429	THROTTLED:<until>	Per-user safety lockout in effect — back off until the timestamp in the body.