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
​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
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.

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.

Last modified 3mo ago