API Keys

Overview

The API keys module gives VillaTax users a controlled way to access the public API surface exposed by the product. It is intentionally practical: create a key, use it to authenticate API requests, revoke it when it is no longer needed. The goal is to make programmatic access to VillaTax data manageable without requiring manual credential sharing or unsafe workarounds.

The module lives at API Keys. The API specification is available at API documentation.

What the Module Supports

The feature covers basic API key lifecycle management:

• Create a new key: generate an access key tied to the authenticated account
• View existing keys: see which keys are active and relevant metadata such as when each key was last used
• Revoke a key: permanently disable a key when an integration is decommissioned or access needs to be removed

That is the correct scope for a V1 API key feature. Advanced capabilities like per-key scoping, expiry dates, or usage quotas are not currently part of the live feature.

API Scope and Ownership

The VillaTax public API is user-scoped. A single API key grants access to all organizations belonging to the authenticated user. There is no per-organization key at this stage. Organization can be targeted as a filter parameter on individual API requests, but one key covers the full account.

The API surface is practical rather than exhaustive. It covers the data and operations most useful for integrations, reporting automation, and external workflows, not a complete CRUD layer over every internal table. The API documentation specification lists the exact available endpoints.

Why API Access Matters

Even a limited API surface creates real value for operators who want to move data beyond the dashboard:

• Reporting automation: pull booking, expense, or compliance data into an external reporting tool without manual export cycles
• External accounting systems: push VillaTax records into a separate bookkeeping product that the accountant prefers to work in
• Custom dashboards: build a property-specific view by combining VillaTax data with other operational data sources
• Integration with management systems: connect VillaTax to a broader property management workflow where multiple data sources need to be unified

The key requirement in all of these cases is a revocable, properly authenticated credential. That is exactly what this module provides.

Security Hygiene

API keys should be treated with the same care as passwords. The module is designed to make good hygiene easy:

• Keys are only shown at creation time. After that, only the metadata (name, last-used date) is visible, not the key value itself.
• If a key is lost, exposed, or suspected compromised, it can be revoked from the dashboard immediately without affecting the account login.
• Creating a separate key per integration context is a good practice: if one integration is shut down, that key can be revoked cleanly without disrupting other active integrations.

Relationship to the Public API

API keys are only useful in the context of what the public API actually exposes. VillaTax's API provides access to supported data and operations; it is not a blanket programming interface to every internal module. Before building an integration, reviewing the API specification at API documentation is the right starting point: it shows which endpoints exist, what parameters they accept, and what data they return.

Outgoing webhooks (where VillaTax pushes events to an external URL when something changes) are a separate feature described in the integrations section, not part of the API key workflow.

Getting Started

Open API Keys when a supported integration or reporting workflow needs programmatic access to VillaTax data. Create a key, copy it at creation time (it will not be shown again), and configure it in the external system. Revoke the key from the same page when the integration is no longer active. Review the key list periodically to confirm that active keys correspond to live, authorized integrations.