Keys
Two kinds of key exist, and they are not interchangeable. The company creates both in its admin, under Developers, and every creation, rotation and revocation is written to the company’s audit log.
Publishable keys
A publishable key (pk_...) is meant to sit in a web page’s code. It allows one thing: sending enquiries and booking requests from the exact origins the company lists on it, such as https://www.example.ae. It is sent in the X-Api-Key header, from the visitor’s browser.
- A request from any other origin is refused with 403.
- A wrong or revoked key is refused before any limit is counted; a valid key is then limited per key.
- The key is tied to the lead types the company allows it to send.
http://localhostorigins are accepted only on development workspaces, never in production.
A publishable key never reads anything: reads need no key at all.
Server keys
A server key (sk_...) is for a server the company trusts: its own back end, a CRM connector, a helpdesk, an accounting package. It is shown once, when created, and stored only as a hash. Send it as Authorization: Bearer sk_..., and only from a server. A key seen in a browser or a public repository should be revoked at once.
Scopes
A key may do only what its scopes allow; a key that is unknown, revoked or without the operation’s scope is refused with 403, never ignored.
| Scope | Allows |
|---|---|
read:listings | The catalogue reads, limited per key instead of per address; GET /api/v1/services takes this or write:leads |
read:team | The published team profiles |
write:leads | POST /api/v1/leads without a publishable key, an origin or a spam-check token: the server answers for what it sends |
read:leads, read:contacts, write:contacts, read:followups, write:followups, read:members | Keeping your CRM in sync |
read:leases, write:leases | Leases |
read:maintenance, write:maintenance | Maintenance |
read:pipelines, write:pipelines | Pipelines |
Rotation
Rotating a key issues a new secret and keeps the old one working for 24 hours, so a deployment can switch without downtime. The admin shows when each key was last used, which tells the company when the old secret can go.
What the company sees
Every read made with a server key that returns personal data is recorded in the audit log with the key’s prefix. Revoking the key stops a sync at once.
Which key for what
| You are | Use |
|---|---|
| Building a public website | No key for reads; a publishable key for the forms |
| Building a server-rendered site that posts enquiries from its server | A server key with write:leads (the browser-to-API rule still applies to visitor forms; see Lead forms) |
| Connecting a CRM, helpdesk or accounting tool | A server key with the scopes of the lines you mirror |