Authentication

Every call to the REST API and the MCP server carries an organization API token: one you create in Settings, or one an app gets by signing you in with OAuth.

Create a token

In PropFit, organization owners and admins open Settings → Integrations → API & integrations. The organization’s plan must include API access; otherwise calls answer 403 not_entitled.

Name it after what will use it (“Buildium sync”, “Claude for Maria”).
Pick its scopes. Read scopes are selected to start with.
Pick an expiry: 30, 90, 180, 365 days. Every token expires.
Copy the token (pf_api_…). It is shown once: PropFit stores only its SHA-256 hash.

Send it

Send the token as a Bearer token. Requests without a valid one answer 401.

curl -s https://developers.propfit.co/api/v1/me \
  -H "Authorization: Bearer $PROPFIT_TOKEN"

/me needs no scope and returns the token’s name, prefix, scopes, expiry and rate limit, and its organization.

Scopes

API scopes
Scope	Name in PropFit	Allows
`read:inventory`	Read inventory	Properties and units.
`write:inventory`	Add inventory	Create properties and units (a PMS import). Never archives or deletes.
`read:offers`	Read vacancies	Status, rent, terms, fees, move-in cost, readiness and link slugs.
`write:offers`	Draft and pause vacancies	Create and edit drafts, pause a published vacancy. Publishing stays in the app.
`read:criteria`	Read criteria	The active policy, its pathways and the compliance-check result.
`read:matches`	Read match summaries	Counts by state and per-renter criterion assertions. Never renter values, names or contact details.
`read:analytics`	Read funnel counts	Aggregate counts per vacancy; counts of 1–4 are hidden.
`write:links`	Create qualification links	A new link with a channel tag.
`read:applications`	Read applications	Status, first-come order, criterion assertions, which kinds of data were shared, and your decision (read only). Deciding stays in the app.
`read:applicant_data`	Read shared applicant data	The values a renter shared with an application (name, contact, income…). Every read is audited and the renter sees it.
`read:background_checks`	Read background check status	Asked, authorized, ordered, done; the result only as pass or needs review. Never the report.
`write:background_checks`	Request background checks	Ask an applicant to authorize the check in your plan. Ordering and the report stay in the app.
`read:tours`	Read tour times	Tour times and who booked them (no contact details).
`write:tours`	Manage tour times	Add tour times to a published vacancy; cancel a time or a booked tour.
`read:reports`	Read reports	Your owner reports; small groups are hidden.
`read:billing`	Read billing summary	Plan, status, subscription and invoice totals. Never card details.
`read:notifications`	Read notification preferences	The token creator’s notification and email preferences.

A call outside the token’s scopes answers 403 insufficient_scope. Match summaries also need a verified organization (403 org_unverified). The API reference lists the scope of every operation.

Sign in with OAuth (MCP clients)

An MCP client that supports OAuth needs only the server URL. Its first call answers 401 with a WWW-Authenticate header naming https://developers.propfit.co/.well-known/oauth-protected-resource/api/mcp. The client registers itself (POST /api/oauth/register), sends you to PropFit to sign in and choose the organization and permissions, and exchanges the code (PKCE S256) at /api/oauth/token.

The access token is an ordinary API token (pf_api_…) that lasts an hour, for the organization and person who signed in, with the permissions they allowed.
The refresh token (pf_rt_…) lasts 30 days and is replaced on every use. Using an old one, or a code twice, ends the connection.
Owners and admins see and disconnect connected apps in Settings → Integrations.
A renter can instead connect an app for just themselves: the token has no organization and only renter scopes (read:homes, read:my_matches, read:my_applications, read:my_tours, read:my_passport) for the /renter/… endpoints. Renters disconnect apps on their Privacy page.

Server metadata: https://developers.propfit.co/.well-known/oauth-authorization-server. Public clients only; no client secrets.

When a token stops working

It expires.
Someone revokes it in Settings.
The person who created it leaves the organization, or stops being an owner or admin.

Treat a token like a password. Keep it in a secret store, never in code or a browser. Give an AI assistant its own token with read scopes only.

Create a token

In PropFit, organization owners and admins open Settings → Integrations → API & integrations. The organization’s plan must include API access; otherwise calls answer 403 not_entitled.

Name it after what will use it (“Buildium sync”, “Claude for Maria”).

Pick its scopes. Read scopes are selected to start with.

Pick an expiry: 30, 90, 180, 365 days. Every token expires.

Copy the token (pf_api_…). It is shown once: PropFit stores only its SHA-256 hash.

Scopes

API scopes
Scope	Name in PropFit	Allows
`read:inventory`	Read inventory	Properties and units.
`write:inventory`	Add inventory	Create properties and units (a PMS import). Never archives or deletes.
`read:offers`	Read vacancies	Status, rent, terms, fees, move-in cost, readiness and link slugs.
`write:offers`	Draft and pause vacancies	Create and edit drafts, pause a published vacancy. Publishing stays in the app.
`read:criteria`	Read criteria	The active policy, its pathways and the compliance-check result.
`read:matches`	Read match summaries	Counts by state and per-renter criterion assertions. Never renter values, names or contact details.
`read:analytics`	Read funnel counts	Aggregate counts per vacancy; counts of 1–4 are hidden.
`write:links`	Create qualification links	A new link with a channel tag.
`read:applications`	Read applications	Status, first-come order, criterion assertions, which kinds of data were shared, and your decision (read only). Deciding stays in the app.
`read:applicant_data`	Read shared applicant data	The values a renter shared with an application (name, contact, income…). Every read is audited and the renter sees it.
`read:background_checks`	Read background check status	Asked, authorized, ordered, done; the result only as pass or needs review. Never the report.
`write:background_checks`	Request background checks	Ask an applicant to authorize the check in your plan. Ordering and the report stay in the app.
`read:tours`	Read tour times	Tour times and who booked them (no contact details).
`write:tours`	Manage tour times	Add tour times to a published vacancy; cancel a time or a booked tour.
`read:reports`	Read reports	Your owner reports; small groups are hidden.
`read:billing`	Read billing summary	Plan, status, subscription and invoice totals. Never card details.
`read:notifications`	Read notification preferences	The token creator’s notification and email preferences.

A call outside the token’s scopes answers 403 insufficient_scope. Match summaries also need a verified organization (403 org_unverified). The API reference lists the scope of every operation.

The access token is an ordinary API token (pf_api_…) that lasts an hour, for the organization and person who signed in, with the permissions they allowed.

The refresh token (pf_rt_…) lasts 30 days and is replaced on every use. Using an old one, or a code twice, ends the connection.

Owners and admins see and disconnect connected apps in Settings → Integrations.

A renter can instead connect an app for just themselves: the token has no organization and only renter scopes (read:homes, read:my_matches, read:my_applications, read:my_tours, read:my_passport) for the /renter/… endpoints. Renters disconnect apps on their Privacy page.

Server metadata: https://developers.propfit.co/.well-known/oauth-authorization-server. Public clients only; no client secrets.