Skip to main content
Every request to the Partner API requires your API key. Pass it in an HTTP header — either Authorization: Bearer (recommended) or X-API-Key.

​
Passing your API key

Send your key as a Bearer token:

​
X-API-Key header (alternative)

If your stack does not manage the Authorization header, use X-API-Key instead:
Both headers are equivalent. If both are present, Authorization takes precedence.
Do not expose your API key in client-side code. Always call the Ochy API from your backend server.

​
Getting an API key

API keys are generated in the Ochy developer portal. Two paths, depending on your account type:
  • Self-serve developers: register at developers.ochy.io/register, verify your email (this grants 1 free analysis credit), then generate your key from the portal. Key generation requires a verified email. See get API access for the full walkthrough.
  • Organizations: once your organization is set up by the Ochy team, an organization admin signs in to the portal and generates the key.

​
Error responses

If authentication fails, the API returns one of these responses:

​
Missing API key — 401

Returned when no API key is provided in the Authorization header or the X-API-Key header.

​
Invalid API key — 403

Returned when the key does not match any active partner account.

​
Rate limits

Requests are limited to 100 per minute per API key and 500 per minute per IP address. The limit is a throttle, not a ban: once you slow down, requests are accepted again. Exceeding it may return 429 Too Many Requests. See limits and reliability for polling budgets and retry guidelines.

​
Credits

Each analysis consumes one credit from your account balance. The credit is debited atomically when the analysis starts, not when results are retrieved. If starting the analysis then fails on our side, the credit is automatically refunded.

​
Scopes

Credits belong to the scope of your API key:
  • Personal keys (self-serve developer accounts) draw from your individual balance.
  • Organization keys draw from the organization’s shared balance.
Your current balance and usage are shown in the Usage & Credits tab of the developer portal.

​
Insufficient credits — 424

Returned when your account has no remaining credits at the time the analysis is started.
To add credits: self-serve developers buy them directly in the developer portal (2.00 € per analysis, prepaid, see get API access); organizations go through their Ochy contact.

​
Low-credit alerts

Set a threshold in the portal Settings tab or with PUT /settings/low-credit-alerts to be warned by email, and optionally by a credits.low webhook event, when an analysis brings your balance to or below it. See low-credit alerts.

​
Security best practices

  • Always pass the key in a header (Authorization: Bearer or X-API-Key).
  • Store your API key in environment variables or a secrets manager — never hard-code it.
  • Rotate your key periodically from the developer portal.
  • Monitor your credit usage and set up low-credit alerts to avoid unexpected exhaustion.