Authentication Rules

API Key

In order to use our APIs, you need to acquire an API key. All you have to do is Login to your account and grab it from your dashboard. Once you have your API key ready you can start issuing requests to our servers. It's that simple!

API Key security information:

Your API Key represents your account. It is important that it always remains a secret and should therefore never be used in any front-end environment where it can be easily read or accessed.

If you happen to misplace your key or suspect that it has been leaked, make sure to immediately revoke/generate a new one in your dashboard.

Making A Request

Making a request to our endpoints is easy. Simply, point your HTTPs client of choice to the desired endpoint URL and provide it with the api_key header along with all the information the endpoint requires. Our servers will then process your request and return the result payload to you.

The base URL for all our endpoints is: https://api.jsonrepo.com/{endpoint}

As our platform name implies, all of our endpoint replies are JSON based. Along with computed response data, the Content-Type: application/json response header will be sent.

A typical response will include: http_code field, http_message field, message field and a payload field (which will be set to an empty array for errors or endpoints that return no data).

Importance of URL-encoding:

Some of our APIs will require you to provide data as query or body parameter(s) for the endpoint to do its job. When sending the required data please make sure that everything is URL-encoded properly. Otherwise, the request may be misinterpreted or dropped altogether.

For more information check the examples in the documentation for your specific endpoint of choice.

UTF-8 everywhere:

Our API endpoints work with a lot of non-english datasets. It is therefore important to make sure that your application accepts and can process UTF-8 data.

Authentication Failure

When the api_key is not provided or an incorrect/invalid one is sent, our service will reject the request and return a 401 HTTP error code response. Similarly, when you exceed your request allowance, the 429 code will be sent. To find out more, see our Error Rules Guide.

A Lorenum.com product

Twitter Discord Email

Request example

  • Curl
// Make a request to one of our endpoints

curl \
https://api.jsonrepo.com/{endpoint} \
-H api_key:{YOUR_API_KEY_HERE}

Successful Response Example

{
    "http_code": 200,
    "http_message": "Ok",
    "message": "Successful execution",
    "payload": {
        "some_key": [...]
    }
}

Failed Authentication Example

{
    "http_code": 401,
    "http_message": "Unauthorized",
    "message": "Malformed request: `api_key` header was not included in the request",
    "payload": []
}