Skip to content
Documentation · Authentication

Getting started

Authentication

Every Properly Platform API request except the health probe carries your API key in a header.

Send x-api-key: <secret> on every request. The only route without it is GET /v1/health. Do not put the key in URLs; header only.

A missing or invalid key returns:

401 Unauthorized detail: "Missing or invalid x-api-key"

A valid key on an account whose Properly subscription has expired, or whose plan doesn't include the API, gets 403 subscription_inactive, not 401. Access returns with the same key once the subscription is reactivated.

Issuing a key

Keys are issued in the Properly web app under Settings → API & AI assistants, to accounts on the Platform Pro and Real-Time Inspection plans.

  • The key is shown once at creation. Store it then.
  • Revocation is immediate from the same page.
  • An assisted path also exists: email api@getproperly.com.

Key lifecycle

  • Keys issued from the web app authenticate the Platform API only. Keys issued before self-serve key management ("legacy keys") work on both APIs until the legacy API retires on April 7, 2027, so create a Platform API key before then.
  • Rate limits are applied per key. See Rate limits.

Example first request

Request 
curl "https://platform.getproperly.com/v1/properties?limit=50" \
  -H "x-api-key: $PROPERLY_API_KEY"
Response · 200 OK 
{
  "data": [
    {
      "propertyId": "8jL2mQxT4a",
      "sourceId": "pms-100234",
      "name": "Seaside Loft 2B",
      "address": "12 Ocean Ave, Santa Monica, CA",
      "pictureUrls": ["https://res.cloudinary.com/…/prop1.jpg"],
      "tags": ["beach"],
      "location": { "latitude": 34.0119, "longitude": -118.4916 },
      "timeZone": "America/Los_Angeles",
      "countryCode": "US",
      "bedrooms": 2,
      "beds": 3,
      "bathrooms": 2,
      "bedDetails": [
        { "bedType": "queen", "twinable": false, "displayLabel": "Master bedroom", "quantity": 1 },
        { "bedType": "sofabed", "twinable": false, "displayLabel": "Living room", "quantity": 1 }
      ],
      "details": { "access": "Lockbox code 4821", "wifiName": "SeasideLoft", "wifiPassword": "surf2026" },
      "createdAt": "2026-05-02T18:11:04.000Z",
      "updatedAt": "2026-08-30T09:20:41.000Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Liveness probe

GET /v1/health 200 OK No auth

Returns 200 with { status, version } when the service is up. This is the only route that needs no API key.

Response fields
Field Type Required Notes
status string Required —
version string Required The deployed API version.
Request 
curl https://platform.getproperly.com/v1/health

Type to search the Platform API docs.