Authentication and API access

API access is for directed developer use. Contact support@ranch.bot to confirm credentials and the farm owner’s authorization before integrating.

Current availability

There is no self-serve developer registration or supported public client installation flow in this release. A working integration needs an authorized Ranch.Bot user, farm access, and credentials provisioned through the directed setup. OAuth requires an active registered client with allowed scopes. Endpoint availability alone does not establish that a public client is ready to install.

Legacy API keys remain implemented but deprecated. They are not part of customer onboarding. Customers need no API key for SMS or the web dashboard. Do not create new key-based onboarding from this reference.

Send credentials

Send the directed access token or legacy key in the Authorization header. Keep credentials in your server environment; do not embed them in a public webpage.

bash example

curl --fail-with-body 'https://api.ranch.bot/v1/farm?skip=0&take=25' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

RANCHBOT_TOKEN is a placeholder environment variable for your own integration. The examples never contain a working credential. Browser cross-origin requests are restricted to the configured Ranch.Bot web origin; use a server-side integration.

Scopes and farm roles

Resource pages list required external scopes such as read:animals and write:records. Read and write scopes are separate. Roles form a hierarchy: OWNER includes EDITOR permissions, and EDITOR includes READER permissions. Scope checks do not replace membership or role checks. A default farm is a convenience, not an access grant.

Most role failures return 401; missing external scopes return 403. Missing active farm membership commonly returns 404. Requests with missing or invalid credentials return 401. Handle status and the documented error body, not only the message text.

Device sessions without a write scope are read-only across the API, apart from the export-job operations explicitly allowed by read:exports. Browser-only account, chat, confirmation, memory-write, and internal observer operations are excluded from this integration reference.

Direct writes and deletion

Direct API writes do not inherit the app’s confirmation screen. Your integration must obtain the user’s intended action before sending a write request. Do not retry a creation automatically after an ambiguous network failure; it may already have saved.

Deletion often marks a record inactive instead of erasing all history. The behavior and required role vary by resource. Check the operation before sending DELETE.

Rate limits and errors

The general production API limit is 100 requests per 15-minute window, per legacy key or otherwise per client IP. Device authorization start allows 30 requests per window; token endpoints allow 240. Use RateLimit headers and respect Retry-After on 429. These are the current implementation limits, not a throughput commitment.

json example

{
  "success": false,
  "errors": [
    { "code": 403, "name": "ForbiddenError", "message": "Missing required scope: write:records" }
  ]
}

OAuth polling has additional protocol-specific error bodies. See the OAuth reference for the implemented endpoints. Follow the directed client setup for authorization, refresh, and revocation; no public client id is provided here.