OAuth API

HTTP reference for oauth. Read authentication and access before using these operations. All examples use made-up data and placeholder credentials.

• GET /oauth/.well-known/oauth-authorization-server
• GET /oauth/authorize
• POST /oauth/device
• POST /oauth/device/token
• POST /oauth/revoke
• POST /oauth/token

GET /oauth/.well-known/oauth-authorization-server

Discovery

Current oauth HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/oauth/.well-known/oauth-authorization-server'

Responses

200 response schema (application/json)

{
  "issuer": "example",
  "authorization_endpoint": "example",
  "token_endpoint": "PLACEHOLDER_CREDENTIAL",
  "revocation_endpoint": "example",
  "userinfo_endpoint": "example",
  "jwks_uri": "https://example.com",
  "response_types_supported": [],
  "grant_types_supported": [],
  "code_challenge_methods_supported": [],
  "scopes_supported": [],
  "token_endpoint_auth_methods_supported": []
}

GET /oauth/authorize

Authorize

Current oauth HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks.

Replace PLACEHOLDER_CLIENT_ID with your registered client ID and https://your-app.example/oauth/callback with your registered callback URL, then URL-encode both values. The example requests read:animals.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/oauth/authorize?client_id=PLACEHOLDER_CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-app.example%2Foauth%2Fcallback&response_type=code&scope=read%3Aanimals'

Responses

POST /oauth/device

Device

Current oauth HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Production rate limit: 30 requests per 15-minute window, per client IP. RateLimit headers report the current window; respect Retry-After on 429. Requires an active registered client and only that client’s allowed scopes. Codes expire after 900 seconds; poll no faster than every 5 seconds. The user approves in the browser. No public self-serve client registration is provided.

Request body (application/json)

{
  "client_id": "11111111-1111-4111-8111-111111111111"
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/oauth/device' \
  -H "Content-Type: application/json" \
  --data '{"client_id":"11111111-1111-4111-8111-111111111111"}'

Responses

200 response schema (application/json)

{
  "device_code": "example",
  "user_code": "example",
  "verification_uri": "https://example.com",
  "verification_uri_complete": "example",
  "expires_in": 1,
  "interval": 1
}

POST /oauth/device/token

Device Token

Current oauth HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Production rate limit: 240 requests per 15-minute window, per client IP. RateLimit headers report the current window; respect Retry-After on 429. Poll with the returned device_code and original client_id. Pending authorization returns an OAuth 400 body. Malformed request bodies return the standard validation 400 envelope. Invalid, consumed, expired, mismatched-client, or disallowed-permission device codes return the standard 401 envelope.

Request body (application/json)

{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "example",
  "client_id": "11111111-1111-4111-8111-111111111111"
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/oauth/device/token' \
  -H "Content-Type: application/json" \
  --data '{"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"example","client_id":"11111111-1111-4111-8111-111111111111"}'

Responses

200 response schema (application/json)

{
  "scope": "read:animals",
  "access_token": "PLACEHOLDER_ACCESS_TOKEN",
  "refresh_token": "PLACEHOLDER_REFRESH_TOKEN",
  "token_type": "Bearer",
  "expires_in": 900
}

400 response schema (application/json)

{
  "error": "authorization_pending",
  "error_description": "The authorization request is still pending"
}

POST /oauth/revoke

Revoke

Current oauth HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Production rate limit: 240 requests per 15-minute window, per client IP. RateLimit headers report the current window; respect Retry-After on 429.

Request body (application/json)

{
  "token": "PLACEHOLDER_CREDENTIAL",
  "client_id": "11111111-1111-4111-8111-111111111111"
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/oauth/revoke' \
  -H "Content-Type: application/json" \
  --data '{"token":"PLACEHOLDER_CREDENTIAL","client_id":"11111111-1111-4111-8111-111111111111"}'

Responses

200 response schema (application/json)

{
  "revoked": true
}

POST /oauth/token

Token

Current oauth HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Production rate limit: 240 requests per 15-minute window, per client IP. RateLimit headers report the current window; respect Retry-After on 429. Authorization-code exchange requires code and redirect_uri. A refresh-token grant requires refresh_token. Use the configured client and its directed setup; do not infer a working public client from endpoint existence.

Request body (application/json)

{
  "grant_type": "authorization_code",
  "client_id": "11111111-1111-4111-8111-111111111111"
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/oauth/token' \
  -H "Content-Type: application/json" \
  --data '{"grant_type":"authorization_code","client_id":"11111111-1111-4111-8111-111111111111"}'

Responses

200 response schema (application/json)

{
  "access_token": "PLACEHOLDER_CREDENTIAL",
  "token_type": "PLACEHOLDER_CREDENTIAL",
  "expires_in": 1,
  "refresh_token": "PLACEHOLDER_CREDENTIAL",
  "scope": "example"
}

Error body

Validation and authentication errors generally use this envelope. Rate-limit errors omit data; OAuth polling also has protocol-specific errors shown in its reference.

{
  "success": false,
  "errors": [
    {
      "code": 400,
      "name": "ValidationError",
      "message": "Example validation failure"
    }
  ]
}