Authentication

Qyvo uses Laravel Passport Personal Access Tokens for all API and MCP traffic. There is one token type — the same value works for the REST API and the MCP server.

Token format

Tokens are opaque strings — typically 60+ characters of hex. They are scoped to:

• the user that created them (their tenant resolves automatically)
• the mcp scope, which authorizes both REST and MCP calls

There is no service account or organization token. Each token is owned by an individual user. Revoking the user revokes their tokens.

Generate a token

1. Sign in to qyvo.io
2. Open Settings → API Tokens
3. Click Create token, give it a name describing the use case (Claude Desktop, n8n production, support script, …)
4. Copy the value once — Qyvo shows the plaintext for 90 seconds, then permanently masks it

If you lose a token, generate a new one and revoke the old one. Qyvo cannot recover the plaintext.

Use a token

Attach it as a Bearer header on every request:

Authorization: Bearer YOUR_TOKEN_HERE

A minimal smoke test in your language of choice:

curl https://www.qyvo.io/api/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

const res = await fetch('https://www.qyvo.io/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.QYVO_TOKEN}` },
});
const me = await res.json();

use Illuminate\Support\Facades\Http;

$me = Http::withToken(env('QYVO_TOKEN'))
    ->get('https://www.qyvo.io/api/v1/me')
    ->json();

import os, httpx

me = httpx.get(
    'https://www.qyvo.io/api/v1/me',
    headers={'Authorization': f"Bearer {os.environ['QYVO_TOKEN']}"},
).json()

All four return the authenticated user and tenant. See GET /v1/me.

Scopes

Currently every token is issued with the single scope mcp. It grants access to:

• All /api/v1/* REST endpoints
• The MCP server at /mcp

There is no narrower scope today. If you need to restrict a token to a subset of endpoints, run an integration server in your own stack and proxy only the calls you want to expose.

Revoke a token

In Settings → API Tokens, click the Revoke action next to the token. Revocation takes effect immediately — in-flight requests using that token fail with 401.

Security best practices

• Never commit tokens. Use environment variables or a secret manager (1Password, Doppler, AWS Secrets Manager, GitHub Actions secrets).
• One token per integration. It makes auditing and rotation surgical — revoking n8n production doesn't break the support script.
• Rotate periodically. Quarterly is a reasonable default. Generate the new token, deploy it, then revoke the old one.
• Don't ship tokens in client-side code. Tokens grant full workspace access; treat them like a database password. For browser/widget contexts, proxy through a server you control.
• Use HTTPS only. Qyvo will redirect any HTTP request, but tokens leaked over plain HTTP should be considered compromised — revoke immediately.

Common errors

Status	Meaning
401 Unauthenticated	Header missing, token misspelled, token revoked, or token has no mcp scope
404 Personal access client not found	Server-side install issue — contact support
422 No workspace configured for this account.	The user behind the token has no tenant — re-check workspace setup

See the full Errors catalogue.