API Keys Guide

API keys are how you securely connect your AI assistant to your Ranch.Bot account. This guide explains everything you need to know about creating, managing, and securing your API keys.

An API key is a secret token that authenticates your AI assistant (like Claude Desktop) with your Ranch.Bot account. It works like a password, but specifically for programmatic access.

When you configure your AI assistant with a Ranch.Bot API key, it can:

  • Access your farm data
  • Create and update animals
  • Record treatments and movements
  • Query your herd information
  • Manage groups and records

From the Dashboard

  1. Go to Settings → API Keys
  2. Click "Create API Key"
  3. Enter a name (e.g., "Claude Desktop", "ChatGPT")
  4. Optionally select a default farm
  5. Click "Create"
  6. Copy the API key immediately.

API Key Format

Ranch.Bot API keys follow this format:

rb_sk_[32-character-secret]

Example: rb_sk_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p

  • rb - Ranch.Bot identifier
  • sk - Secret key type
  • [secret] - Your unique 32-character secret

Name

A friendly name to help you remember where this key is used.

  • Good: "Claude Desktop - Mac", "ChatGPT Work", "Gemini Mobile"
  • Avoid: "key1", "test", "asdf"

Default Farm

Optionally set a default farm for this API key. When set, MCP operations will automatically use this farm unless you specify otherwise.

Benefits:

  • Faster queries - don't need to specify farm each time
  • Cleaner prompts - "List my animals" instead of "List animals in Smith Ranch"
  • Better UX - AI assistant knows your context

Status

  • Active - Key is working and can be used
  • Revoked - Key has been disabled (can be deleted)
  • Expired - Key has passed its expiration date (auto-revoked)

Editing a Key

You can update:

  • Name - Change the friendly name
  • Default Farm - Change or remove the default farm
  • The key itself - Cannot be changed (create a new key instead)

Revoking a Key

When to revoke:

  • The key was compromised or leaked
  • You're no longer using that AI assistant
  • You want to rotate keys for security

How to revoke:

  1. Go to Settings → API Keys
  2. Find the key you want to revoke
  3. Click "Revoke"
  4. Confirm the action
Tip

Revoked keys can be deleted permanently. Active keys cannot be deleted (must revoke first).

Deleting a Key

You can only delete revoked or expired keys. This prevents accidental deletion of active keys.

  1. Revoke the key first
  2. Click "Delete"
  3. Confirm (this cannot be undone)

Best Practices

DO:

  • Store keys securely in your AI assistant's config file
  • Use different keys for different devices/applications
  • Revoke keys immediately if compromised
  • Set expiration dates for temporary access
  • Monitor usage regularly
  • Use descriptive names

DON'T:

  • Share your API key publicly (GitHub, forums, screenshots)
  • Email or message API keys
  • Use the same key everywhere
  • Keep unused keys active
  • Store keys in plain text files

Monitoring Usage

Track your API key activity:

  1. Go to Settings → API Keys
  2. View "Last Used" timestamp for each key
  3. Check usage patterns for anomalies

Personal Use (Single Device)

Name: "Claude Desktop - Personal" Default Farm: [Your primary farm]

Multiple Devices

Key 1: "Claude Desktop - Mac" Key 2: "ChatGPT - iPhone" Key 3: "Gemini - Work Laptop"

Team Collaboration

Key 1: "John - Claude Desktop" Key 2: "Sarah - ChatGPT" Key 3: "Mike - Gemini"

Development/Testing

Name: "Development Testing" Default Farm: "Test Farm" Expiration: 7 days

API Key Not Working

Error: "Invalid API key" or "Unauthorized"

Solutions:

  1. Verify you copied the entire key (starts with rb_sk_)
  2. Check the key hasn't been revoked (Settings → API Keys)
  3. Confirm the key hasn't expired
  4. Ensure there are no extra spaces or line breaks in your config
  5. Try creating a new key

Can't See Full Key

Problem: Lost or forgot to copy the API key.

Solution: You cannot recover the full key. Create a new one:

  1. Revoke the old key (if you can identify it)
  2. Create a new API key
  3. Update your AI assistant configuration
  4. This time, save the key in a password manager.

Key Shows as Expired

Problem: Key has passed its expiration date.

Solution:

  1. The key is automatically revoked and cannot be used
  2. Create a new API key
  3. Update your AI assistant configuration

Usage Not Showing

Problem: "Last Used" shows "Never" but you've been using it.

Explanation: Usage tracking updates every few minutes. Wait a bit and refresh the page. If it still shows "Never" after 5 minutes:

  1. Verify your AI assistant is properly configured
  2. Check that requests are actually reaching Ranch.Bot
  3. Contact support if issue persists

Scopes and Permissions (Coming Soon)

Future versions will support granular permissions:

  • read:animals - Read-only access to animals
  • write:animals - Full access to animals
  • read:records - Read-only access to records
  • write:records - Full access to records

API Key Rotation

For enhanced security, rotate keys periodically:

  1. Create a new API key
  2. Update your AI assistant config with the new key
  3. Test that the new key works
  4. Revoke the old key
  5. Delete the old key after confirming everything works

Recommended rotation schedule: Every 90 days for production use

Multiple Farms

If you manage multiple farms:

  1. Create separate API keys for each farm
  2. Set the default farm for each key
  3. Name them clearly: "Claude - North Ranch", "Claude - South Ranch"
  4. This keeps your data organized and queries fast

Common Issues:

Still need help?

Next: MCP Server Setup →