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 the callback 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 for callback

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

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.

Oauth authorisation screen