Authentication

Every Roxy API request requires an API key. No OAuth, no tokens, no sessions.

Key types

Two key classes follow the Stripe convention. Pick the one that matches where the call is made from.

pk_ keys can be safely placed in client-side JavaScript, HTML widgets, mobile app bundles, and no-code platform configs. Bind each pk_ key to one or more allowed origins (your website domains) and a leak from one of those origins becomes an empty exploit: the attacker hits your monthly quota and gets 403 origin_not_allowed from anywhere else.

pk_ keys are NOT accepted on the MCP endpoints (/mcp/*). MCP is server-side traffic with no Origin header to enforce, so a leaked publishable key there would be free tool access. Use a secret key for MCP.

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. Mint additional keys (secret or publishable) from your account page anytime.

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();

Using a publishable key in the browser

A publishable key can be sent over Authorization: Bearer ... from any front-end. This avoids the extra preflight a custom header would force.

<script>
  fetch('https://roxyapi.com/api/v2/tarot/draw', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pk_live_your_publishable_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ count: 1 })
  })
    .then((r) => r.json())
    .then(console.log);
</script>

When the request runs from a browser, the browser sends an Origin header automatically. The server compares its host against the allowlist on your key (case-insensitive, protocol and port ignored, no wildcards), so you list plain domains like yourdomain.com and both http and https work. Mismatch returns 403 origin_not_allowed.

If you set no origins on a publishable key, every response includes the header X-Roxy-Warning: publishable_key_has_no_origin_restrictions. Add at least one origin before shipping to production.

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 25,000 to 3,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