ForBrains API v2 Documentation
Introduction
This page is intended to be read by someone with basic programming experience, but none of the code on this page is intended for production use. We will assume you have access to a WebBrowser like Chrome, Safari, Edge, Opera or Firefox on a desktop environment, or access to a Linux command line.
This guide allows you to code to our APIs without having your own Access Token.
Quick Start Guide
- Open the Javascript Console
- Copy, paste and run:
- await fetch("https://dc01-apiv2.chit.eu:31162/Access/AccessTokenDetails",{method:'GET',headers:{Authorisation:"Bearer 321accesstokenhere123"},keepalive: false}).then(r=>r.json()).then(d=>{console.log(d);}).catch(e=>{console.error('Error:', e);});
- You should see something in the form of:
{"expet":1697975954,"cltm":103}
If you do not see this, do not proceed. Please contact our support team.
AccessToken Tester
| Your public IP: | |
| Allowed IPs: |
Setup Step 1 - your own AccessToken
Next you need your own "AccessToken".
To get one of those you need a Username and Password to an account.
Next replace 321accesstokenhere123 with your own token and repeat the test
| Paste your AccessToken here: |
Now if you copy and run this code in your Javascript Console you should see something like: {"expet":1697975954,"cltm":119}
Do not proceed if your AccessToken is invalid for some reason. Please contact our support team.
If you get: {"err":"FO4"} - your AccessToken is invalid (possibly long expired, log back in using your Username and Password and get a new AccessToken)
IF HERE, YOU HAVE A VALID ACCESS TOKEN
If you are developing on a Linux OS the following may be of use:
wget --no-check-certificate -qO- --header="Authorisation: Bearer 321accesstokenhere123" "https://dc01-apiv2.chit.eu:31162/Access/AccessTokenDetails"
curl -X GET -H "Authorisation: Bearer 321accesstokenhere123" "https://dc01-apiv2.chit.eu:31162/Access/AccessTokenDetails"
If coding in Python create a file: GetAT.py (run it with: python3 GetAT.py)
import requests
u = "https://dc01-apiv2.chit.eu:31162/Access/AccessTokenDetails"
h = {"Authorisation": "Bearer 321accesstokenhere123"}
try:
r = requests.get(u, headers=h)
r.raise_for_status()
print(r.json())
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
If coding in PHP
$token = "321accesstokenhere123";
$url = "https://dc01-apiv2.chit.eu:31162/Access/AccessTokenDetails";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER,["Authorisation: Bearer $token","Content-Type: application/json"]);
$r = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Error: ' . curl_error($ch);
} else {
echo $r;
}
curl_close($ch);
If you get
{"err":"FO4"}
- your AccessToken is invalid (possibly long expired)
{"expet":1697975954,"cltm":118}
- your AccessToken is valid
If seeing this, your access token expires 1697975954 seconds after 1970-01-01 00:00:00 UTC
Which is: 2023-10-22T11:59:14Z
cltm = Calls Left This Minute (by default you can make 120 API calls to us per minute)
ONLY PROCEED WITH THIS GUIDE ONCE YOU HAVE RUN SOME CODE
AND UNDERSTAND WHEN YOUR ACCESS TOKEN EXPIRES
Setup Step 2 - GET / POST / DELETE
You have done a "GET" API request, and have that working. We shall now step up the pace.
There are two other types of requests we need to master before moving onto the full API; these are POST and DELETE
curl -k -X GET -H "Authorisation: Bearer 321accesstokenhere123" "https://dc01-apiv2.chit.eu:31162/Access/AuthorisedAPIIP"
{"ips":["192.168.98.7","*"]}
curl -k -X POST -H "Authorisation: Bearer 321accesstokenhere123" -H "Content-Type: application/json" -d '{"ips": ["192.168.0.4", "192.168.0.7", "192.168.0.14"]}' "https://dc01-apiv2.chit.eu:31162/Access/AuthorisedAPIIP"
{"s":"ok"}
curl -k -X GET -H "Authorisation: Bearer 321accesstokenhere123" "https://dc01-apiv2.chit.eu:31162/Access/AuthorisedAPIIP"
{"ips":["192.168.98.7","*","192.168.0.4", "192.168.0.7", "192.168.0.14"]}
curl -k -X DELETE -H "Authorisation: Bearer 321accesstokenhere123" -H "Content-Type: application/json" -d '{"ips": ["192.168.0.14", "192.168.0.4"]}' "https://dc01-apiv2.chit.eu:31162/Access/AuthorisedAPIIP"
{"s":"ok"}
curl -k -X GET -H "Authorisation: Bearer 321accesstokenhere123" "https://dc01-apiv2.chit.eu:31162/Access/AuthorisedAPIIP"
{"ips":["192.168.98.7","*", "192.168.0.7"]}
Valid ips are:
* - allow access from all IP addresses
92.54.152.9 - a single IPv4 address
95.14.60.8/30 - a range of IPs 95.14.60.8 - 95.14.60.11
95.14.60.8-95.14.69.130 - a range of IPs 95.14.60.8 - 95.14.69.130
IF HERE YOU CAN USE AN ACCESS TOKEN TO DO A GET, POST & DELETE
Setup Step 3 - care of your AccessToken
You are already aware that an AccessToken expires. curl -X GET -H "Authorisation: Bearer 321accesstokenhere123" "https://dc01-apiv2.chit.eu:31162/Access/AccessTokenDetails" Tells you when your token will expire. It may be in like 24hrs time or maybe a weeks time. It is strongly recommended that you do not let your AccessToken expire. It is recommended that you store your AccessToken securely and use it at least once every 8 hours. Four things we recommended you now do: 1) Store your AccessToken securely on your server, maybe in a database or non-publicly accessible file 2) Add your Servers, Office/Home IP address into the AuthorisedAPIIP list curl -k -X GET "https://dc01-apiv2.chit.eu:31162/Access/MyIP"
3) Remove the "*" from the AuthorisedAPIIP list 4) Setup something that automatically calls AccessTokenDetails once every 8 hours The following may be of help if you use cron: 12 2,10,18 * * * sleep $((RANDOM \% 61)) && curl -k -X GET -H "Authorisation: Bearer 321at" "https://dc01-apiv2.chit.eu:31162/Access/AuthorisedAPIIP"
If you do the above, your AccessToken is locked to your computers for added security, and will never expire / be ready for use whenever you need it.
Setup StepP 4 - SDKs
We have various SDKs available to aid a speedy integration.
YOU ARE NOW READY FOR THE FULL API
There are two types of AccessToken
1) Belonging to an Organisation
2) Belonging to a specific Person or Computer Program
Each of these demos show basic implementation of our SDKs. For details of all API endpoints see the full reference guide.
Javascript: https://innovate2020.cashlessschool.co.uk/api/v2/demo-js.html
Javascript Chit SDK
Load the JS SDK, once loaded an instance of a class will exist: ChitAPI
< script src="https://api.chit.eu/v2/chit-js-sdk.js">< /script>
eg. chit_cls_cc~321accesstokenhere123
Set your AccessToken
ChitAPI.InitAPI(< YOUR_ACCESSTOKEN >,{< API_OPTIONS >});
Make calls
Chit.API.Call(< JSON_DATA >,< CALL_CBF >);
if < JSON_DATA.mid > is set then is passed to your CBF instead of < JSON_DATA.data >
ChitAPI.Call( {"endpoint":"Access/MyIP" ,"action":"GET" ,"data":{}} ,true ).then(t=>{
ChitAPI.Call( {"endpoint":"Access/AuthorisedAPIIP" ,"action":"POST" ,"data":{"ips":[t.reply.ip]},"mid":12}, false );
ChitAPI.Call( {"endpoint":"Access/AuthorisedAPIIP" ,"action":"POST" ,"data":{"ips":[t.reply.ip]}} ,false );
});
If you want the results of Calls passed to a function of yours
ChitAPI.SetAsyncCallBackFunc(ChitAPIAsyncResult);
If you want debug information, create a div and pass the id into
ChitAPI.SetDebugContainer(< DIV_ID >);
Yet to be written up
CashlessSchool / Ordo
To perform any action on behalf of a system user you need to gain access to their account.
Every account has a Username and MD5 hash of the users password.
When the user types their password only an md5 hash of it sent from the browser to the server.
We do not know any passwords chosen by a user; only the MD5 hash of them.
curl -X GET -d '{"u":"parent","p":"31F83B4B453DB071F374FA73365B8283"}' -H "Content-Type: application/json" -H "Authorisation: Bearer 321accesstokenhere123" "https://apiv2.cashlessschool.co.uk:31162/AgentAccount"
If credentials are correct you will be given a "aat" (AgentAccessToken)
To create an empty unverified account, take the users password as an md5 hash, mobile phone number, email, first name, last name, and chosen username
curl -X POST -d '{"u":"parent","p":"31F83B4B453DB071F374FA73365B8283","ut","Agent","t":"+447703184699","e":"sales@forbrains.com","fn":"Peter","ln":"Smith"}' -H "Content-Type: application/json" -H "Authorisation: Bearer 321accesstokenhere123" "https://apiv2.cashlessschool.co.uk:31162/AgentAccountCreate"
curl -X POST -d '{"aat":"TheAgentsAccessToken","t":"+447703184699","e":"sales@forbrains.com","fn":"Peter","ln":"Smith"}' -H "Content-Type: application/json" -H "Authorisation: Bearer 321accesstokenhere123" "https://apiv2.cashlessschool.co.uk:31162/AgentAccount"
GET /Access/TokenDetails calling this extends expiry date by 7 days
GET /Access/AuthorisedAPIIP list IPv4 addresses
POST /Access/AuthorisedAPIIP?ip=< csv list > add IPv4 addresses
DELETE /Access/AuthorisedAPIIP?ip=< csv list > remove IPv4 addresses
POST /Agent/AccountCreate to create an Agents account
GET /Agent/AccessToken gain access to an Agents account
POST /Agent/Account to update personal Agents account details. et is mandatory, the other fields are optional to update
List all Serving Premises
await fetch("https://dc01-apiv2.chit.eu:31162/Caterer/ServingPremises", {
method: 'GET', headers: {Authorisation:"Bearer 321accesstokenhere123",keepalive: false}
});