Authentication#

Every request to the YourNextHome API must include an organization API key as a bearer token. Keys are scoped to a single organization; they cannot read or write data belonging to another organization.

#Minting a key

1. Sign in to the dashboard as an organization admin.
2. Open Organization → API Access.
3. Click Generate key, give it a recognizable label (e.g. crm-sync), and copy the secret. It is shown once, so store it in your secrets manager immediately.

#Sending the key

Pass the key as a bearer token in the Authorization header on every request:

curl https://api.yournexthome.app/api/v1/estate \
  -H "Authorization: Bearer ynh_live_xxxxxxxxxxxxxxxxxxxx"

#Rotating and revoking

Keys can be revoked at any time from Organization → API Access. Revoked keys stop working immediately. To rotate, generate a fresh key, switch traffic to it, then revoke the old one. There is no automatic key expiry today.

#Scopes and permissions

A key can call the endpoints documented in this reference, and only those. It reads and writes its own organization's data; a request for a resource owned by another organization returns 404, and any endpoint outside the documented partner surface (internal dashboard and admin operations) returns 403.

Today a key has full read/write access within its organization across every documented resource. We may add scoped keys later. If your integration only needs read access, design for that constraint now so the switch is painless.