# Access and permissions

Create, scope, rotate and retire company integration credentials.

## Company access

An administrator of an existing, verified Homito company creates a key under **Settings → API & agents**. This requires their Homito user session and `settings.edit` permission. The secret is shown once: put it in your server's secret manager. The key determines the company; passing a different company ID cannot extend its access. External self-service company registration is unavailable. Key management uses the Homito web-app origin and its user session, not this external API origin.

## Choose a task and its permissions

| Task | Key permissions | Start here |
| --- | --- | --- |
| Read properties and units | `read:properties` | `GET /api/v1/landlord/inventory/properties` |
| Read published and unpublished listings; synchronize adverts | `read:properties`; `write:properties` for the corresponding mutation | `GET /api/v1/landlord/listings`, `GET /api/v1/landlord/listings/changes`, `PATCH /api/v1/landlord/listings/{unitId}/content`, `POST /api/v1/landlord/listings/{unitId}/media/uploads`, `POST /api/v1/landlord/listings/{unitId}/media/uploads/{uploadId}/complete`, `PATCH /api/v1/landlord/listings/{unitId}/media`, `PATCH /api/v1/landlord/listings/{unitId}/publication` |
| Read tenant contacts | `read:tenants` | `GET /api/v1/landlord/tenants` |
| Read lease timelines | `read:leases` | `GET /api/v1/landlord/leases` |
| Read application summaries | `read:applications` | `GET /api/v1/landlord/applications` |
| Preview and commit properties and units | `write:properties`; `read:properties` for readback | `POST /api/v1/landlord/portfolio-imports/preview` |
| Read or import commercial rent rolls | `read:rent-roll`; `write:rent-roll` for import | `GET /api/v1/landlord/rent-roll` |
| Read or update operational work | `read:fault-reports`, `read:work-orders`; `write:fault-reports`, `write:work-orders` for the corresponding mutation | `GET /api/v1/landlord/fault-reports`, `GET /api/v1/landlord/work-orders` |
| Read or conduct commercial inspections | `read:inspections`; `write:inspections` for mutations | `GET /api/v1/landlord/commercial-inspections` |
| Read or use commercial tenant assistance | `read:commercial-assistance`; `write:commercial-assistance` for mutations | `GET /api/v1/landlord/commercial-assistance` |
| Start a screening and read certified status | `write:screenings`, `read:screenings`; `read:applications` to select a candidate | `POST /api/v1/landlord/screenings` |
| Register webhooks and monitor deliveries | `write:webhooks`, `read:webhooks` | `POST /api/v1/landlord/webhooks` |
| Use the customer-server application intake budget or hosted eID handoff | `write:applications` on a separate server key | `POST /api/v1/public/units/{slug}/application-eid/handoffs` |

## Know the human and portal boundaries

| Action | Available path | Human/portal boundary |
| --- | --- | --- |
| First company access; create, rotate or revoke a key | Authenticated administrator control plane | Existing verified company, user session and `settings.edit` required |
| Ordinary authorized reads and supported writes | External REST API; supported MCP tools after verified distribution | No dashboard interaction required for each ordinary operation |
| Edit advert name and unit text | Listing content PATCH; supported MCP tool after verified distribution | Requires current `write:properties`; media and publication require their separate explicit listing delegation |
| Screening execution, Detective and operator casework | Separate StaySafe service | Homito's integration returns only the permitted certified landlord projection |
| Decisions about applicants and inspection review | Their explicitly authorized decision/review operations | Key possession or an agent instruction does not replace human authority or separation of duties |

## Rotate and retire credentials

For rotation, create a replacement key with the same or narrower permissions, deploy it to the integration and verify an authenticated read. Before revoking the old key, finish or reconcile its outstanding previews and jobs using the old key. A replacement key does not inherit their job IDs or history. Then revoke the old key. The administrator uses **Settings → API & agents** or its authenticated `/api/v1/settings/api-keys` control plane. A company integration key is not an administrator session. Key IDs are non-secret references, not credentials; the raw key cannot be retrieved later. Verify that the retired key is rejected.

## Keep private data out of public caches

Keep personal data, receipts and upload capabilities out of public listing caches. Tenant and application reads intentionally return minimized operational projections; do not infer missing private fields or screening conclusions. Keep nullable/unknown values distinct from zero or a completed result.

## Use the published contract version

Use the API version and lifecycle shown in the API reference, the schemas for each operation, and any required form or resource version when updating an integration. Preserve opaque versions unchanged and pin an approved MCP release. Event names come from the same catalog as the API; arrival order and a product version are not substitutes for current resource readback.