Authentication
Every request to the CFT API must include an application-level API key, to verify that the client application is authorised to make the given request.
Additionally, requests to view or change user data require a user-level API key, to ensure that the user has given permission to that specific application.
Both keys are 43-character alphanumeric strings.
Warning
API and app keys should be kept secret; please do not send them via unencrypted email or store them in version control.
If you send a request without valid authentication data, you will receive an HTTP 403 forbidden response:
$ curl -i "https://app.coolfarmtool.org/api/v1/farm/"
HTTP/1.1 403 FORBIDDEN
$ curl -I \
-H "X-Api-Authorization: kS9UayP3WU7cLQHi5XUW9GylaToRcUtCuY12MPCyyb0" \
-H "X-Api-App-Authorization: OWyHsuoAk74FLDGIGqrgWVBsffG32ndAhsyO1jeuU34" \
"https://app.coolfarmtool.org/api/v1/farm/"
HTTP/1.0 200 OK
Application-level API keys
Request an API key for your application by contacting the Cool Farm Alliance – or, if you are running your own instance, log in to the admin area, then click “Api” → “Applications” → “Add”
Include your application API key in requests as an X-API-APP-Authorization
header (example above), or an api_app_key
request parameter .
User-level API keys
Each Cool Farm Tool user is assigned a unique API key. Users can look up their API key on the “Help” page once logged in, and provide it to your application.
Include the user’s API key in requests as an X-API-Authorization
header
(example above), or an api_key
request parameter.
Applications can retrieve a user’s API key by sending a username and password to
POST /user/key/
.
Registering a new account
If the user does not have a CFT account already, you can assist them in creating one by sending details to pre-fill on the registration form.
- GET /account/register/
You can pre-fill details for the registration form by providing query parameters named according to the existing HTML form fields.
Note
This URL must be opened in the user’s browser in order to complete the registration process; a server-side or AJAX request to
/account/register/
will likely not work. If you need to have information returned, use thecallback
parameter- Form Parameters
str username – desired username
str email – user email address
str callback – URL to send API key of new user after activation
str app_id – numeric ID of your application. Required for
callback
str hash – SHA256 hash of app key concatenated with
callback
, required forcallback
Example request
GET /account/register/ HTTP/1.1 Host: app.coolfarmtool.org Accept: application/json X-APP-Authorization: ... username=test&email=test@example.com&callback=https://example.com/cft&hash=a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2&app_id=1
Example response
HTTP/1.1 302 FOUND Set-Cookie: csrftoken=...; ... sessionid=...; ... Content-Type: text/html; charset=utf-8 Location: ...
- Status Codes
400 Bad Request – missing or incorrect form data
Oauth 2 - Beta
What is OAuth?
OAuth is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords. – `Whitson Gordon`_
The Cool Farm Tool currently only supports Oauth2 and the ‘Authorization Code’ workflow.
Request a Client ID and a Client Secret for your application by contacting the Cool Farm Alliance
Warning
Client Secret should be kept secret; please do not send them via unencrypted email or store them in version control.
OAuth workflow
To start the Authorization code flow go to /o/authorize/. As described below, a few parameters are required.
- GET /o/authorize/
- Query Parameters
response_type (str) – code
client_id (str) – client ID
redirect_uri (str) – URL callback to redirect to once authorisation has been granted
Example request
GET /o/authorize/ HTTP/1.1 Host: app.coolfarmtool.org response_type=code&client_id=vW1RcAl7Mb0d5gyHNQIAcH110lWoOW2BmWJIero8&redirect_uri=https://my_application.org/callback/
app.coolfarmtool.org/o/authorize/?response_type=code&client_id=vW1RcAl7Mb0d5gyHNQIAcH110lWoOW2BmWJIero8&redirect_uri=https://my_application.org/callback/
Users will then be asked to grant your application access to their Cool Farm Tool data. If they are not logged in already, they will be redirected to the Cool Farm Tool login page first.
