DAFWA use two forms of authentication for our Restful services. In order to use both forms you will have to register with the DAFWA website.
- API Key
- OAUTH2
API Key
Registered users can create multiple API keys from within the 'profile' section of the website.
In order to use your registered API Key DAFWA's Server will check for a custom HTTP header called 'api-key'.
HTTP headers are used in sending requests and receiving responses, and they carry information about the client browser, the requested page, the server and more. The custom header you send will allow access to all of the public available API's (provided the API Key is valid).
The api-key can also be used in the uri as an extra parameter if you simply want to paste the address into your internet browser.
eg.
https://api.agric.wa.gov.au/v1/weatherstations/dailysummary.json&api_key=<your api key here>
OAUTH
OAUTH provides multiple access methods based on your needs. DAFWA supports the OAUTH 2.0. specification. The following are the grant-types offered by OAUTH;
- Implicit
- Authorization code
- Password credentials
- Client credentials
- Refresh token
Before you can use OAUTH you must first register your application with DAFWA's website. The registration of your application is managed within the profile section of your DAFWA account.
Which one do I choose?, How does it work?
Looking at the OAUTH specification for a non techy can be daunting, in fact for a 'techy' it is sometimes confusing on which type should be used and whats involved. The following overviews will help make the decision easier.
Implicit
Mobile or client side applications which will need the authorisation from a registered DAFWA user account.
1. Application requests authorisation.
2. User Authorises application.
3. Authorisation server will redirect back to the client and include access token.
4. Access token can now be used by application to make requests.
5. Data returned when valid Access token is included with requests.
Authorization code
This grant type is the most commonly used as its optimised for server side applications where the source code is more secure.
1. Application requests authorisation.
2. User authenitcates(if not logged in) and authorises the application.
3. Receive authorisation code grant.
4. Request access token for given authorisation code.
5. Receive granted access token.
6. Access token can now be used by application to make requests.
7. Data returned when valid Access token is included with requests.
Password credentials
Note: DAFWA does not currently support this grant type.
The users password credentials would have to be provided to the application.
1. Client enters password credentials into application.
2. Request token passing credentials to Auth server.
3. Receive access token.
4. Access token can now be used by application to make requests.
5. Data returned when valid Access token is included with requests.
Client credentials
Note: DAFWA does not currently support this grant type.
This is where an application can send its client id and secret in exchange for an access token.
1. Application request token (with client id and secret).
2. Receive access token.
3. Access token can now be used by application to make requests.
4. Data returned when valid Access token is included with requests.
Refresh token
After an access token expires, using it to make a request from the API will result in an "Invalid Token Error". At this point, if a refresh token was included when the original access token was issued, it can be used to request a fresh access token