Introduction

The Atlas of Living Australia (ALA) is Australia’s national biodiversity database. It is a collaborative, digital infrastructure that aggregates Australian biodiversity data from multiple sources, making the information open, accessible and reusable. The ALA delivers trusted data services for Australia, supporting world-class biodiversity research and decision-making.

These data stored in the ALA have been fully parsed, processed and augmented with consistent taxonomic, geolocation and climate/environmental data. Our data API provides access to over 100 million species occurrence records as well as taxonomic and scientific name information for over 153,000 species, complete with geospatial, taxonomic and temporal searching & filtering as well as bulk downloads for use ‘offline’.

Documentation

Welcome to the ALA API Portfolio Hub.

We’ve recently moved to this API Gateway to streamline access and improve security for end-users by incorporating user authentication. ALA data are still open and freely accessible. For more information or assistance, please contact support@ala.org.au.

API Endpoint: api.ala.org.au

ALA APIs allow two main methods of access

1. No Authentication - The majority of the API endpoints across all published ALA services do not require authentication and are open to public access.

2. JWT Authentication/Advanced Access - For API endpoints that provide write access and read access to sensitive or private data, the requestor (user or machine) needs to be authenticated. JWT access token can used to authenticate requests. The Authentication section provides details on JWT usage.

Authentication

Open ID Connect is used to obtain an access token. Once an access token is obtained it should be passed as a bearer token in the HTTP Authentication header.

Authorization: Bearer <access_token>

Client application details are required for access token generation. Please follow this step-by-step guide for Client Registration and Token Generation. The Token Generation functionality of the guide implements the ALA recommended Authentication Code Flow using PKCE flow mentioned below.

We support multiple ways to obtain an access token:

• Client Credentials
• Authentication Code Flow
• Implicit Flow

The Postman Collection below shows some examples of the above token generation flows and the subsequent usage of the generated token.

Which authentication method should I use?

Machine to Machine (No end user)

Anytime the system is not concerned with end user identity then Client Credentials should be used. The use case would be a headless client application that does not have the ability for user interaction. In this case the system may need to be authenticated however an end user will not.

End User Authentication

If the end user does need to be authenticated then Authentication Code Flow should be used. How you use Authentication Code Flow depends on whether the application client is public or private. Regardless of your client's publicity, Proof Key for Code Exchange (or PKCE) can, and should, be used as an additional security measure when authenticating within your application.

For private client applications (eg. server side web application), you will need a clientId and clientSecret in order to authenticate. Please contact support@ala.org.au to obtain these.

For public client applications (eg. Single-Page or JavaScript application), you will just need a clientId. Implicit Flow can also be used for public client authentication, however Authentication Code Flow using PKCE is the recommended mechanism.

Additional Resources

See Authentication Code Flow using PKCE - Examples

See https://auth0.com/docs/get-started/authentication-and-authorization-flow

See OIDC Authentication for R

🔒 indicates the relevant API is a protected API and it requires authentication.

Discovery

Example response:

{
   "issuer":"https://auth.ala.org.au/cas/oidc",
   "scopes_supported":[
      "openid",
      "profile",
      "... more scopes",

   ],
   "claims_parameter_supported":true,
   "...metadata"
}

OpenID Connect includes a discovery mechanism, where metadata for an OpenID server can be accessed.

GET https://auth.ala.org.au/cas/oidc/.well-known

Examples of what the metadata includes are:

• OpenID/OAuth Endpoints
• Supported Scopes & Claims
• Public Keys

Client Credentials

To authorize, use this code:

# Exchange the client credentials (client ID & secret) for an access token
curl --user {clientId}:{clientSecret}  -X POST -d 'grant_type=client_credentials' -d 'scope={scope}' 'https://auth.ala.org.au/cas/oidc/oidcAccessToken'

# Use the access_token in the Authorization header
curl "api_endpoint_here" \
  -H "Authorization: Bearer {access_token}"

import http.client
import base64

oauth_host = "https://auth.ala.org.au"
oauth_port = 443
oauth_path = "/cas/oidc/oidcAccessToken"
scope = "openid+email"
conn = http.client.HTTPSConnection(oauth_host, oauth_port)
payload = f"grant_type=client_credentials&scope={scope}"

headers = { 
  'Authorization': 'Basic {}'.format(base64.b64encode(bytes(f"{clientId}:{clientSecret}","utf-8")).decode("ascii")),
  'content-type': "application/x-www-form-urlencoded" 
}

conn.request("POST", oauth_path, payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

The Client Credentials grant type is used for machine to machine authentication where there is no user interaction.

POST https://auth.ala.org.au/cas/oidc/oidcAccessToken

Header Parameters:

Request Parameters:

Authentication Code Flow

The postman http client supports the authorisation code flow. When configured the user will be prompted to authenticate prior to accessing a protected API enpoint.

GET https://auth.ala.org.au/cas/oidc/oidcAuthorize

Request Parameters:

POST https://auth.ala.org.au/cas/oidc/oidcAccessToken

Header Parameters:

Request Parameters:

Implicit Flow

The postman http client supports the implicit authorisation flow. When configured the user will be prompted to authenticate prior to accessing a protected API enpoint.

The Implicit Flow is used for apps that have no “back end” logic on the web server, like a Javascript app.

The Implicit flow presents an authorisation page that will prompt a user for credentials before redirecting to the supplied redirect_url with the access_token.

GET https://auth.ala.org.au/cas/oidc/oidcAuthorize

Request Parameters:

Authentication Code Flow using PKCE is recommended for authenticating public clients, as Implicit Authentication reveals the accessToken when the end-user is redirected back to the application, introducing a security risk.

Services

1. Alerts

Services for interacting with the ALA Alerts app, including view alert details, unsubscribe from and create an alert.

For full api documentation see Open API specification

2. Occurrences

Services for interacting species occurrence records.

Explore interactively on the ALA BioCache app.

For full api documentation see Open API specification

3. Surveys

Interact with the ALA BioCollect app, such as searching for projects, surveys and activities.

For full api documentation see Open API specification

4. Species

Services for species profile data.

Explore interactively on the ALA Biodiversity Information Explorer app.

For full api documentation see Open API specification

5. Metadata

Services for interacting with attribution information, such as data provider metadata and citations.

Explore interactively on the ALA Collectory app.

For full api documentation see Open API specification

6. Data Quality Service

Interact with ALA data quality filters.

Explore interactively on the ALA Data Quality Filter Service app.

For full api documentation see Open API specification

7. DOI

Generate DOIs for ALA applications.

Explore interactively on the ALA DOI app.

For full api documentation see Open API specification

8. Galah

Access a curated list of common ALA services.

ALA services required for Galah can be accessed via Common APIs, a curated list of APIs commonly used by the ALA, partners, and public users. An API key (which can be requested from ALA Support) is required for access. Please note that this API key is not used for authentication but rather for usage tracking, monitoring, and rate limiting due to the expected high frequency of usage on these endpoints. The postman 'Run in Postman' link below demonstrates the usage of these APIs with API key. Further usage documentation on these APIs can be found in the corresponding service sections (e.g. Alerts, Logger etc) under Services.

For full api documentation see Open API specification

9. Images

Access ALA images, such as finding an image by keyword.

Explore interactively on the ALA Images app.

For full api documentation see Open API specification

10. Download statistics

Interact with the ALA Logger Logger webapp, such as getting event types and reason breakdowns.

For full api documentation see Open API specification

11. Species lists and traits

Interact with species lists , including get list details and create a list.

For full api documentation see Open API specification

12. User details

Access the ALA user details platform, such as a total count of users in the system and users by role.

For full api documentation see Open API specification

13. Spatial

Services for interacting with ALA Spatial services

Explore interactively on the ALA Spatial app.

For full api documentation see Open API specification  

14. Events

Access the ALA Events app.

For full api documentation see Open API specification

15. Profiles service

Services for interacting with ALA Profile collections

Explore interactively on the ALA Profile collection app.

For full api documentation see Open API specification  

16. Sensitive

Services for interacting with Sensitive Data Service

Explore interactively on the ALA sensitive service.

For full api documentation see Open API specification  

17. Namematching

Access the ALA namematching service.

For full api documentation see Open API specification

18. Fieldguide

Access the ALA fieldguide service.

For full api documentation see Open API specification

Errors