Account management and signup

This page covers the complete account management lifecycle for the vario API: from initial registration to credential rotation. All examples use the production base URL https://api.vario.lat.

1. API account registration

`POST /api/public/api-signup`

Creates an API-only account with 250 free trial credits. No prior authentication required. Once the account is created, the API key is also sent by email.

Authentication: none (public endpoint, rate-limited to 5 requests/min).

Request parameters:

Field	Type	Required	Description
`email`	`string`	Yes	Corporate email. Free-domain emails are not accepted.
`name`	`string`	Yes	Full name of the applicant.
`organization`	`string`	Yes	Name of the organization.

Request example:

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

Response 201 example:

{
  "api_key": "vario_xbGhABC123...WXYZ",
  "credits_balance": 250,
  "warning": "Store this key immediately. It cannot be recovered — only revoked and replaced."
}

ℹ

Important: the api_key is shown only once in this response. Store it immediately in a secrets manager. vario does not store the full key value — if you lose it, you must revoke it and generate a new one.

Possible errors:

HTTP	Code	Condition
`409`	`email_already_registered`	The email already has a registered account.
`422`	`VALIDATION_ERROR`	Free-domain email, invalid format, or missing field.
`429`	`RATE_LIMIT_EXCEEDED`	Exceeded 5 requests per minute.

2. Account information

`GET /api/v1/api-portal/me`

Returns the current account state: identity, account type, subscription status, and credit balance.

Authentication: Authorization: Bearer vario_YOUR_API_KEY or SSO (web portal session).

Request example:

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

Response 200 example:

{
  "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "name": "Ana Beatriz Souza",
  "organization": "Forensic Firm LATAM",
  "account_type": "api_only",
  "subscription_status": "trial",
  "credits_balance": 247,
  "api_keys_count": 1
}

Response fields:

Field	Type	Description
`tenant_id`	`string` (UUID)	Unique tenant identifier. Immutable.
`email`	`string`	Email associated with the account.
`name`	`string`	Name of the account holder.
`organization`	`string`	Name of the registered organization.
`account_type`	`string`	`"api_only"` for accounts without seats. `"saas"` for accounts with a SaaS subscription.
`subscription_status`	`string`	`"trial"` / `"active"` / `"past_due"` / `"canceled"`.
`credits_balance`	`integer`	Credits available in the current balance.
`api_keys_count`	`integer`	Number of active API keys associated with the account.

3. List API keys

`GET /api/v1/api-portal/keys`

Returns all active API keys for the account. The full value of each key is not included in the response — only a key_hint is shown for visual identification.

Authentication: Authorization: Bearer vario_YOUR_API_KEY or SSO.

Request example:

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

Response 200 example:

[
  {
    "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Production — CADE matter 2026",
    "key_hint": "vario_xbGh...WXYZ",
    "scopes": ["analyze:run", "playbooks:list"],
    "is_active": true,
    "last_used_at": "2026-06-01T18:45:00Z",
    "created_at": "2026-05-15T10:00:00Z",
    "expires_at": null
  },
  {
    "key_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "CI pipeline",
    "key_hint": "vario_yZaB...VWXY",
    "scopes": ["analyze:run"],
    "is_active": true,
    "last_used_at": "2026-06-02T08:12:00Z",
    "created_at": "2026-05-20T14:30:00Z",
    "expires_at": "2027-05-20T00:00:00Z"
  }
]

Response fields:

Field	Type	Description
`key_id`	`string` (UUID)	Unique identifier for the key. Used to revoke it.
`name`	`string`	Descriptive label assigned when creating the key.
`key_hint`	`string`	First 10 and last 4 characters of the token. For visual identification only.
`scopes`	`list[string]`	Permissions enabled on this key.
`is_active`	`boolean`	`false` if the key has been revoked.
`last_used_at`	`string` (ISO 8601)	Last time this key made a successful request. `null` if never used.
`created_at`	`string` (ISO 8601)	Creation date.
`expires_at`	`string` (ISO 8601) \| `null`	Configured expiration date, or `null` if it does not expire.

4. Create an additional API key

`POST /api/v1/api-portal/keys`

Generates a new API key for the account. Only available via SSO (active web portal session) — cannot be invoked using an existing API key as a credential.

Authentication: SSO (active session in the web portal).

Request parameters:

Field	Type	Required	Description
`name`	`string`	Yes	Label to identify this key.
`scopes`	`list[string]`	No	Valid values: `"analyze:run"`, `"playbooks:list"`. Default: all.
`expires_at`	`string` (ISO 8601)	No	Expiration date. If omitted, the key does not expire.

Response 201 example:

{
  "key_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "key": "vario_newXYZ789...ABCD",
  "name": "CI pipeline",
  "scopes": ["analyze:run"],
  "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."
}

5. Revoke an API key

`DELETE /api/v1/api-portal/keys/{key_id}`

Revokes an API key permanently and immediately.

Authentication: Authorization: Bearer vario_YOUR_API_KEY or SSO.

curl -X DELETE https://api.vario.lat/api/v1/api-portal/keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer vario_YOUR_API_KEY"

Response 204 No Content — no body.

ℹ

Immediate effect: there is no grace period. Any request authenticated with the revoked key fails with 401 from the moment of revocation.

6. Quick API key rotation

`POST /api/public/api-keys/rotate`

Invalidates the current API key and generates a new one with the same scopes in a single operation. Designed for security incident response.

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

Response 200 example:

{
  "key": "vario_newABC123...WXYZ",
  "key_hint": "vario_newABC...WXYZ",
  "warning": "Store immediately — not shown again. The previous key is now invalid."
}

ℹ

Recommended rotation sequence:

Execute POST /api/public/api-keys/rotate.
Store the new key immediately.
Update the environment variable in all services that were using the previous key.
Verify that the services respond correctly with the new key.

Credential management best practices

Never include the API key in source code. Use environment variables or a secrets manager.
One key per environment. Create separate keys for development, staging, and production.
Use a descriptive name. Makes it easier to identify which service uses each key.
Set expires_at for short-lived keys. Useful for temporary integrations.
If compromise is suspected: use POST /api/public/api-keys/rotate immediately.

Complete onboarding flow

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

# Initial balance: 250 trial credits

# Step 2: Verify the account
curl https://api.vario.lat/api/v1/api-portal/me \
  -H "Authorization: Bearer vario_YOUR_API_KEY"

# Step 3: View active keys
curl https://api.vario.lat/api/v1/api-portal/keys \
  -H "Authorization: Bearer vario_YOUR_API_KEY"