Base URL

The current REST API endpoint is:

https://www.app.ocoya.com/api/_public/v1

Send your API key in the X-API-Key header.

X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Create API key

Who can use the API

An API key belongs to the person who created it, and works in every brand where that person is an owner or an admin. One key covers all of those brands; there are no per-brand keys.

Your role in a brandCreate tokensA token reaches the brand
OwnerYesYes
AdminYesYes
ManagerNoNo
ClientNoNo
  • Only owners and admins can create API keys, under Settings → API.
  • The brands a key reaches are checked on every request, from its owner’s role at that moment. Lose admin rights to a brand and the key stops reaching it; be made an admin of one and it starts.
  • GET /me and GET /brands list exactly the brands the key reaches. A request for any other brand fails with 403 Invalid brand id or you do not have access to this brand.

Test Your API Key

Call /me to verify the key.

curl -X GET "https://www.app.ocoya.com/api/_public/v1/me" \
  -H "X-API-Key: YOUR_API_KEY"

If the key is valid, the API responds with your user context instead of an authentication error.

Authentication Errors

Missing API key

If no API key is provided, the API returns 401 Unauthorized.

{
  "message": "Missing API token."
}

Invalid API key

If the API key is invalid, the API returns 403 Forbidden.

{
  "message": "Invalid API token."
}

Security Notes

Keep keys server-side

API keys are designed for backend requests. Do not use them directly in browser-side code.

Store keys securely

Store API keys in environment variables or a secrets manager.

Rotate exposed keys

Replace an API key if it appears in client code, logs, screenshots, or public repositories.

MCP Authentication

MCP does not use Ocoya API keys. MCP clients authenticate through OAuth and ask the user to approve brand access.

See MCP for setup instructions.