API Authentication & API Keys
The three credentials Seayora accepts, live versus test keys, what a credential can see, and how to keep keys safe.
Three accepted credentials
An API key is a single token, shown once at creation. Send it as a bearer token — this works against both https://seayora.com/api/v1 and https://seayora.com/mcp, which is the simplest way to wire up an agent framework that does not speak OAuth.
Authorization: Bearer sy_live_ak_1a2b3c4d_XwPq…Split headers carry the same key, cut at the last underscore. Offered because it matches the shape most property-management integrations are already written against.
X-Seayora-Client-Id: ak_1a2b3c4d
X-Seayora-Client-Secret: XwPq…An OAuth access token is what an assistant gets after the consent screen. Short-lived and refreshed automatically by the client.
Authorization: Bearer sy_at_9f8e7d…Live and test keys
A key is minted as either sy_live_… or sy_test_…. A test key authenticates identically and reads real data, so your output is realistic — but every write is refused with the error code test_mode. Develop against a test key, switch the string when you ship.
What a credential can see
A credential returns your account's data and nothing else. Being an admin does not widen it — a key belongs to a person and returns that person's view. Scope is enforced server-side on every call, not in the client: a tool the credential lacks the permission for is not merely hidden from the catalogue, calling it directly is refused.
Creating a key
- Settings → AI & integrations → API keys → New key.
- Pick a preset — read-only is right for most reporting and sync jobs — or tick permissions individually. Only permissions your kind of account can hold are offered.
- Optionally set an expiry, a requests-per-minute limit, a monthly cap and an IP allowlist. Set them low for a key you are handing to someone else.
- Copy the key when it is shown. It is shown once; if you lose it, rotate the key and copy the replacement.
Rotating and revoking
Rotating a key gives you a new secret now and keeps the old one working for 24 hours so you have time to deploy. Revoking stops it immediately. Both are on the API keys screen, and both are logged.
Your first call
curl https://seayora.com/api/v1/me \
-H "Authorization: Bearer sy_live_ak_…"
{
"data": {
"email": "[email protected]",
"role": "landlord",
"plan": "pro",
"granted_scopes": ["properties:read", "..."],
"environment": "live"
},
"request_id": "req_8f1c2b…"
}/me is the right first call: it tells you which permissions the credential actually holds, so you never have to guess why something later returns 403.
Frequently asked questions
Where do I keep the key?
In your software's secret store or environment, never in a repository or a shared document. If a key is ever exposed, rotate it — the old one stops working within 24 hours, or revoke it to stop it now.
Related guides
Related features and guides
- API Requests & Responses — Documentation. The response envelope, paging, the money and date conventions, and how writes work on the Seayora REST API.
- API Rate Limits & Error Codes — Documentation. The error shape, every stable error code and what to do about it, rate-limit headers, and how to retry well.
- Permissions Reference — Documentation. Every permission an assistant or API key can hold, what it unlocks, and which ones can change records — generated from the server.