IDBUT Solutions API Authentication

This document contains instructions and important information for how the Authentication System works in IDBUT Solution's API. This Documentation DOES NOT contain information for the actual API Usage methods. Please refer to the appropriate documentations that are linked on IDBUT Solutions

Authentication Methods 🔒

There are two types of methods for authentication, the first method is the most common form of authentication which is the use of a API Key, the second method is the use of a certificate.

API Key 🔐

The API Key identifies your account on IDBUT Solutions, it is a simple form of authentication which is used with the parameter api_key in either a POST or GET request, the examples given in this documentation will explain how to accomplish this

Certificate 🔏

A Certificate is represented as a .crt file, which is non-standard. this is sent to the server under the certificate parameter with the contents base64 encoded. This also works with a POST or GET request. The purpose of a certificate is designed for user-friendly clients which would simply prompt the user for a certificate file (which is downloaded off the IDBUT Solutions Web Application) instead of a API Key.

Authentication used with a certificate is very similar to authentication used with a API Key, with the only difference is that the contents of the certificate is base64 encoded before it gets sent to the server.

Multiple Authentication Methods Notice

Although no errors will be raised when using both an API Key and Certificate during authentication, the certificate will simply be ignored even if the API Key is invalid.

🚩 It is recommended to only use one form of authentication

Authentication Examples 🔍

When this documentation talks about "Parameters", we are talking about the values within a GET request or a POST request (URL Parameters or multipart/form-data). The API Doesn't care where you place your values, for as long as it sent appropriately within the supported request method. This means you can include your API Key in the URL while the rest of your request parameters in a POST Request Body if that's your style.

API Key Example ⭐

Authentication using a API Key is simply done with the api_key parameter.

GET Request

GET /api/v1/exampleMethod?api_key=123 HTTP/1.1
Host: idbutsolutions.io

POST Request

POST /api/v1/exampleMethod HTTP/1.1
Content-Length: 80
Host: idbutsolutions.io
Content-Type: application/x-www-form-urlencoded

api_key=123

POST Request but with api_key as the GET parameter

POST /api/v1/exampleMethod?api_key=123 HTTP/1.1
Content-Length: 7
Host: idbutsolutions.io
Content-Type: application/x-www-form-urlencoded

foo=bar

Certificate Example ⭐

Authentication using a Certificate is simply done with the certificate parameter but the contents of the certificate must be base64 encoded.

For this example the certificate we are using is gonna be

991f920eaea73e5318c45e758b6f5215de46eb4c5cf52bd975a080cac19e743cf5a5d9ca6cdb270885de1541c98d38cdqqwc5a4a5d4b7f382410dfe959de7a52bea197108bdd7cbea81fd3be9f5d74cfa67eccc2200dc1fc20449cc48b4ccfbfb9c9ad9a2258fad8b67agdscbc8ea8452ab1f07937abf7e5cd405071b69ba9c0(467f25f58976f499684db5lol228775179c1se7dv3059a89bdsf26dsf513e8bc9e2c162fa7ed43e2c1a0005adf9dce6d1d2ac3ddb4827af79889074f185f40ad71c8a030d15d969d5deeaf5b162b8dc5bd2ac67c0db74a362bf7949eaed6d717987aa1e80d0da0a2f926470c562bee2f3ed40e03c940dsfaa670f5d400820c28)^36245fsdg34g3226e99000e284fbas53-31570468/idbut-solutions

When converted to base64, the output is

OTkxZjkyMGVhZWE3M2U1MzE4YzQ1ZTc1OGI2ZjUyMTVkZTQ2ZWI0YzVjZjUyYmQ5NzVhMDgwY2FjMTllNzQzY2Y1YTVkOWNhNmNkYjI3MDg4NWRlMTU0MWM5OGQzOGNjZTY0YzVhNGE1ZDRiN2YzODI0MTBkZmU5NTlkZTdhNTJiZWExOTcxMDhiZGQ3Y2JlYTgxZmQzYmU5ZjVkNzRjZmE2N2VjY2MyMjAwZGMxZmMyMDQ0OWNjNDhiNGNjZmJmYjljOWFkOWEyMjU4NzhkOGI2N2ExZmZjYmM4ZWE4NDUyYWIxZjA3OTM3YWJmN2U1Y2Q0MDUwNzFiNjliYTljMCg0NjdmMjVmNTg5NzZmNDk5Njg0ZGI1ZmNjMjI4Nzc1MTc5YzExZTcyOTMwNTlhODliN2M2MjY3MWQ1MTNlOGJjOWUyYzE2MmZhN2VkNDNlMmMxYTAwMDVhZGY5ZGNlNmQxZDJhYzNkZGI0ODI3YWY3OTg4OTA3NGYxODVmNDBhZDcxYzhhMDMwZDE1ZDk2OWQ1ZGVlYWY1YjE2MmI4ZGM1YmQyYWM2N2MwZGI3NGEzNjJiZjc5NDllYWVkNmQ3MTc5ODdhYTFlODBkMGRhMGEyZjkyNjQ3MGM1NjJiZWUyZjNlZDQwZTAzYzk0MGFjMGFjNjcwZjVkNDAwODIwYzI4KV4zNjI0NWY4NDI5MDZmMjI2ZTk5MDAwZTI4NGZiNGQ1My0zMTU3MDQ2OC9pZGJ1dC1zb2x1dGlvbnM=

GET Request

GET /api/v1/exampleMethod?certificate=OTkxZjkyMGVhZWE3M2U1MzE4YzQ1ZTc1OGI2ZjUyMTVkZTQ2ZWI0YzVjZjUyYmQ5NzVhMDgwY2FjMTllNzQzY2Y1YTVkOWNhNmNkYjI3MDg4NWRlMTU0MWM5OGQzOGNjZTY0YzVhNGE1ZDRiN2YzODI0MTBkZmU5NTlkZTdhNTJiZWExOTcxMDhiZGQ3Y2JlYTgxZmQzYmU5ZjVkNzRjZmE2N2VjY2MyMjAwZGMxZmMyMDQ0OWNjNDhiNGNjZmJmYjljOWFkOWEyMjU4NzhkOGI2N2ExZmZjYmM4ZWE4NDUyYWIxZjA3OTM3YWJmN2U1Y2Q0MDUwNzFiNjliYTljMCg0NjdmMjVmNTg5NzZmNDk5Njg0ZGI1ZmNjMjI4Nzc1MTc5YzExZTcyOTMwNTlhODliN2M2MjY3MWQ1MTNlOGJjOWUyYzE2MmZhN2VkNDNlMmMxYTAwMDVhZGY5ZGNlNmQxZDJhYzNkZGI0ODI3YWY3OTg4OTA3NGYxODVmNDBhZDcxYzhhMDMwZDE1ZDk2OWQ1ZGVlYWY1YjE2MmI4ZGM1YmQyYWM2N2MwZGI3NGEzNjJiZjc5NDllYWVkNmQ3MTc5ODdhYTFlODBkMGRhMGEyZjkyNjQ3MGM1NjJiZWUyZjNlZDQwZTAzYzk0MGFjMGFjNjcwZjVkNDAwODIwYzI4KV4zNjI0NWY4NDI5MDZmMjI2ZTk5MDAwZTI4NGZiNGQ1My0zMTU3MDQ2OC9pZGJ1dC1zb2x1dGlvbnM%3D HTTP/1.1
Host: idbutsolutions.io

POST Request

POST /api/v1/exampleMethod HTTP/1.1
Content-Length: 778
Host: idbutsolutions.io
Content-Type: application/x-www-form-urlencoded

certificate=OTkxZjkyMGVhZWE3M2U1MzE4YzQ1ZTc1OGI2ZjUyMTVkZTQ2ZWI0YzVjZjUyYmQ5NzVhMDgwY2FjMTllNzQzY2Y1YTVkOWNhNmNkYjI3MDg4NWRlMTU0MWM5OGQzOGNjZTY0YzVhNGE1ZDRiN2YzODI0MTBkZmU5NTlkZTdhNTJiZWExOTcxMDhiZGQ3Y2JlYTgxZmQzYmU5ZjVkNzRjZmE2N2VjY2MyMjAwZGMxZmMyMDQ0OWNjNDhiNGNjZmJmYjljOWFkOWEyMjU4NzhkOGI2N2ExZmZjYmM4ZWE4NDUyYWIxZjA3OTM3YWJmN2U1Y2Q0MDUwNzFiNjliYTljMCg0NjdmMjVmNTg5NzZmNDk5Njg0ZGI1ZmNjMjI4Nzc1MTc5YzExZTcyOTMwNTlhODliN2M2MjY3MWQ1MTNlOGJjOWUyYzE2MmZhN2VkNDNlMmMxYTAwMDVhZGY5ZGNlNmQxZDJhYzNkZGI0ODI3YWY3OTg4OTA3NGYxODVmNDBhZDcxYzhhMDMwZDE1ZDk2OWQ1ZGVlYWY1YjE2MmI4ZGM1YmQyYWM2N2MwZGI3NGEzNjJiZjc5NDllYWVkNmQ3MTc5ODdhYTFlODBkMGRhMGEyZjkyNjQ3MGM1NjJiZWUyZjNlZDQwZTAzYzk0MGFjMGFjNjcwZjVkNDAwODIwYzI4KV4zNjI0NWY4NDI5MDZmMjI2ZTk5MDAwZTI4NGZiNGQ1My0zMTU3MDQ2OC9pZGJ1dC1zb2x1dGlvbnM%3D

Authentication Errors

If you simply did not provide the correct parameters to authenticate or the authentication method fails you will be receive a JSON response explaining the error, alongside with the appropriate HTTP Error Codes. Below are a examples of possible responses for authentication failures

Authentication Required ❗

This is returned when the server expected an authentication method but none was given

{
    "status": false,
    "code": 401,
    "message": "Authentication is required"
}

Incorrect Authentication ⛔

This is returned when the given authentication data is incorrect/invalid

{
    "status": false,
    "code": 401,
    "message": "Incorrect Authentication"
}

Suspended 🔥

This is returned if your Access Key was suspended (Certificate or API Key)

{
    "status": false,
    "code": 403,
    "message": "Your access key has been suspended"
}

This documentation was written with ❤️ by netkas

Netkas/idbut_api_authentication.md