Authentication

Information about sending authenticated requests

Mandatory authentication

In order to use our API you will need to authenticate using your API key that you created within the Ocoya dashboard. You can create it here.

Using API keys on the client-side

API keys are designed for server-side usage and they should not be used directly on the client-side making AJAX calls because then they will be exposed publicly. We advise you to make all requests on the server-side due to security concerns.

API keys

Create your API key here!

API keys are a quick way to implement machine-to-machine authentication without any direct inputs from a human beyond initial setup. For example, you might want to run a scheduled job to post on socials using your Ocoya account.

You can generate an API key by opening Ocoya, navigating to Integrations and choosing API. Once the key is generated, please copy and store it immediately. We will not be able to show this API key again in the future, as we don't store API keys in plain text for security reasons. If you lose it, you will have to replace it with a new API key.

Once you have your API key, provide it in an X-API-Key header, together with your request payload, where XXXX is your token:

X-API-Key: XXXX

That's it! You should now be able to send requests to any of our endpoints successfully.

Authenticated request sample

cURL

curl --request GET \
     --url https://app.ocoya.com/api/_public/v1/me \
     --header 'X-API-Key: XXXX'

Node.js

const me = await fetch('https://app.ocoya.com/api/_public/v1/me', {
    method: 'GET',
    headers: {
      'Content-type': 'application/json',
      'X-API-Key': 'XXXX'
    }
  })
    .then(res => res.json())
    .catch(e => throw new Error(`An unknown error occurred`))

Authentication errors

You might encounter validation errors as follows.

When API key is not provided

If you fail to provide a token, you'll get this response on all requests:

Response Code: 401 Unauthorized
Content-Type: application/json

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

When API key is invalid

If you provide an invalid token, you might encounter validation errors when sending requests to API endpoints. They will come in the following format:

Response Code: 403 Forbidden
Content-Type: application/json

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

HTTP status codes

Our API returns standard HTTP response codes.

Code	Name	Explanation
200	OK	The request was accepted.
201	Created	Resource was created.
202	Accepted	There was an error when processing your request. Please adjust your request based on the endpoint requirements and try again.
204	No Content	The request was accepted and there is nothing to return.
400	Bad Request	There was an error when processing your request. Please adjust your request based on the endpoint requirements and try again.
401	Unauthorized	The provided API token is invalid.
403	Forbidden	The action is denied for that account or a particular API token.
404	Not Found	The requested resource does not exist on the system.
405	Method Not Allowed	HTTP method is not supported by the requested endpoint.
408	Request Timeout	There is an error on our system. Please contact support.
422	Unprocessable Entity	There was a validation error found when processing the request. Please adjust it based on the endpoint requirements and try again.
429	Too Many Requests	There were too many requests made to the API.
500	Internal Server Error	There is an error on our system. Please contact support.
502	Bad Gateway	There is an error on our system. Please contact support.
503	Service Unavailable	There is an error on our system. Please contact support.
504	Gateway Timeout	There is an error on our system. Please contact support.