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