Authentication & API keys

All routes of the vario public API require a valid API key. This document describes how to obtain one, how to use it in each request, and how to manage it securely throughout your integration lifecycle.

1. Authentication

The vario API uses API keys as its authentication mechanism. Each key has the prefix vario_ and is included in the Authorization header of each request as a Bearer token.

Authorization: Bearer vario_YOUR_API_KEY

Example with curl:

curl https://api.vario.lat/v1/playbooks \
  -H "Authorization: Bearer vario_YOUR_API_KEY"

Any request without this header, or with an invalid, inactive, or expired key, receives a 401 response.

2. How to obtain an API key

Portal registration

Register at the vario developer portal by providing your corporate email and the name of your organization. Upon completing registration, the system automatically generates your first API key and displays it only once on screen. It is also sent to the registered email address.

curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "org_name": "Forensic Firm LATAM"
  }'

Response 201:

{
  "key": "vario_xbGhABC123...WXYZ",
  "warning": "Store this key immediately. It cannot be recovered — only revoked and replaced.",
  "free_credits": 250,
  "call_cost_screening": 1,
  "call_cost_fast": 2,
  "call_cost_full": 3,
  "docs_note": "$0.150 per credit. Pricing is subject to change."
}

Upon registration you receive 250 free credits to explore the API.

Additional keys

Once registered, you can create additional keys from the portal or via the API. This is useful for separating credentials by use case, team, or project.

curl -X POST https://api.vario.lat/api/v1/api-keys \
  -H "Authorization: Bearer vario_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CADE matter 2026 integration",
    "scopes": ["analyze:run", "playbooks:list"],
    "expires_at": "2027-06-01T00:00:00Z"
  }'

Response 201:

{
  "key_id": "uuid",
  "key": "vario_newXXX...ABC",
  "name": "CADE matter 2026 integration",
  "scopes": ["analyze:run", "playbooks:list"],
  "expires_at": "2027-06-01T00:00:00Z",
  "created_at": "2026-06-02T10:00:00Z",
  "warning": "Store this key immediately. It will not be shown again."
}

The key field only appears in the creation response. After that, the portal only shows a key_hint (first and last characters) for visual identification — the full token cannot be recovered.

3. Key security

A vario API key grants access to your tenant's endpoints. Treat it like a password.

Best practices:

• Use environment variables to inject the key into your application. Never write it directly in source code.
• Never include an API key in frontend code (browser JavaScript, mobile apps). Keys are server-side credentials.
• Never commit a key to a public repository (GitHub, GitLab, etc.). If you did so by mistake, revoke it immediately and generate a new one.
• Use separate keys per context: one for staging, one for production, one per third-party integration where applicable.

# Correct: environment variable
export VARIO_API_KEY="vario_YOUR_API_KEY"

curl https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer $VARIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Scopes

Each key has one or more scopes that limit the endpoints it can invoke:

If a request uses a key without the required scope, the API returns 403 INSUFFICIENT_SCOPE. When creating a key, grant only the scopes necessary for that use case.

4. Key management from the portal

The developer portal shows all active API keys for your tenant. From there you can:

List active keys

curl https://api.vario.lat/api/v1/api-keys \
  -H "Authorization: Bearer vario_YOUR_API_KEY"

Response 200:

[
  {
    "key_id": "uuid",
    "name": "CADE matter 2026 integration",
    "key_hint": "vario_xbGh...WXYZ",
    "scopes": ["analyze:run", "playbooks:list"],
    "is_active": true,
    "last_used_at": "2026-06-02T09:00:00Z",
    "expires_at": "2027-06-01T00:00:00Z",
    "created_at": "2026-06-02T10:00:00Z"
  }
]

The key_hint field shows the first and last characters of the token so you can visually identify each key without exposing its full value.

Revoke a key

When a key is no longer in use, or if you suspect it was compromised, revoke it using its key_id. Revocation is immediate and irreversible.

curl -X DELETE https://api.vario.lat/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer vario_YOUR_API_KEY"

Response: 204 No Content

Revocation deactivates the key without deleting its record. Usage history is preserved in the tenant's audit trail.

5. Key rotation

Rotation generates a new key with the same scopes as the current one and revokes the previous one in a single atomic operation.

curl -X POST https://api.vario.lat/api/public/api-keys/rotate \
  -H "Authorization: Bearer vario_YOUR_API_KEY"

Response 200:

{
  "key": "vario_newABC123...WXYZ",
  "key_hint": "vario_newABC...WXYZ",
  "warning": "Store immediately — not shown again."
}

When to rotate:

• Suspicion that the key was exposed (public repository, visible log, traffic capture).
• Periodic rotation as part of your organization's security policy.
• Change of team responsible for the integration.

What happens to in-flight calls during rotation:

The previous key becomes inactive at the moment the rotation endpoint is executed. Any in-transit request using the old key will receive 401 INVALID_API_KEY. Configure your client to retry with the new key immediately after receiving it.

6. Rate limits per key

Each API key has rate limits according to the tenant's plan. When the limit is exceeded, the API returns 429 RATE_LIMIT_EXCEEDED with the Retry-After header indicating the seconds until the next available slot.

Specific limits by plan are documented in Errors & rate limits.

7. Complete authentication example

# Register account and obtain initial key
curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "org_name": "Forensic Firm LATAM"
  }'

# Save the key from the response as an environment variable
export VARIO_API_KEY="vario_xbGhABC123...WXYZ"

# Verify access: list available playbooks
curl https://api.vario.lat/v1/playbooks \
  -H "Authorization: Bearer $VARIO_API_KEY"

# Send a text for analysis
curl -X POST https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer $VARIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Acordamos no bajar de $450 la unidad.",
    "playbook": "price_fixing",
    "language": "es",
    "mode": "fast"
  }'

Authentication errors