Ocoya API
Search
K
Comment on page

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

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
Node.js
curl --request GET \
--url https://app.ocoya.com/api/_public/v1/me \
--header 'X-API-Key: XXXX'
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
When API key is invalid
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."
}
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.