Authentication

Every Roxy API request requires an X-API-Key header. No OAuth, no tokens, no sessions.

Getting your API key

1. Go to roxyapi.com/pricing
2. Pick a plan and complete checkout
3. Your API key is displayed immediately and emailed to you

No account required. No approval queue. Instant activation.

Using your API key

Headers are metadata you send along with your request. Think of the API key header like showing your ID at a door — the server checks it before letting your request through.

Include the X-API-Key header in every request:

curl https://roxyapi.com/api/v2/astrology/horoscope/aries/daily \
  -H "X-API-Key: your_api_key_here"

const response = await fetch('https://roxyapi.com/api/v2/astrology/horoscope/aries/daily', {
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

Error responses

All errors return { "error": "message", "code": "machine_readable_code" }. The error field is a plain-English description. The code field is stable and safe to switch on in your code (e.g., validation_error, api_key_required, rate_limit_exceeded). See the SDK docs for the full error codes table.

Rate limits

Rate limit info is included in every response header:

• X-RateLimit-Limit — your monthly request allowance
• X-RateLimit-Remaining — requests left this month

Plans range from 5,000 to 1,000,000 requests/month. All endpoints count the same: one request, regardless of complexity.

Security best practices

Never expose your API key in client-side code. Anyone who views your page source can steal your key. This is what NOT to do:

<!-- DANGER: Anyone can see your key by viewing page source -->
<script>
  fetch('https://roxyapi.com/api/v2/tarot/daily', {
    headers: { 'X-API-Key': 'roxy_live_abc123...' }
  });
</script>

Instead, call Roxy from your backend server and return the results to your frontend. The Starter Apps show this pattern in practice.

Other best practices:

• Use environment variables to store your key (ROXY_API_KEY), not hardcoded strings in your code.
• Rotate your key if it is ever exposed. Contact support for a new key.

Next steps

• SDK Setup — typed API calls in TypeScript and Python
• MCP Setup — connect AI agents via Model Context Protocol