| title | language_tabs | toc_footers | includes | search | code_clipboard | meta | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Atlas of Living Australia API Documentation |
|
|
|
true |
true |
|
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’.
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: "<%= I18n.t(:baseUrl) %>"
ALA APIs allow two main methods of access
-
No Authentication - The majority of the API endpoints across all published ALA services do not require authentication and are open to public access.
-
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.
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:
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
🔒 indicates the relevant API is a protected API and it requires authentication.
Example response:
{
"issuer":"<%= I18n.t(:oidcIssuer) %>",
"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 <%= I18n.t(:oidcIssuer) %>/.well-known/openid-configuration
Examples of what the metadata includes are:
- OpenID/OAuth Endpoints
- Supported Scopes & Claims
- Public Keys
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}' '<%= I18n.t(:oidcHost) %>/oauth2/token'
# Use the access_token in the Authorization header
curl "api_endpoint_here" \
-H "Authorization: Bearer {access_token}"import http.client
import base64
oauth_host = "<%= I18n.t(:oidcHost) %>"
oauth_port = 443
oauth_path = "/oauth2/token"
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 <%= I18n.t(:oidcHost) %>/oauth2/token
Header Parameters:
| Parameter | Mandatory | Default | Description |
|---|---|---|---|
| Authorization | Y | base64 encoded <clientId>:<clientSecret> |
|
| Content-Type | Y | application/x-www-form-urlencoded |
Request Parameters:
| Parameter | Mandatory | Default | Description |
|---|---|---|---|
| grant_type | Y | Set to client_credentials |
|
| scope | N | A space separated list of scopes that have been approved for the API Authorization client. These scopes will be included in the Access Token that is returned. |
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 <%= I18n.t(:oidcHost) %>/oauth2/authorize
Request Parameters:
| Parameter | Mandatory | Default | Description |
|---|---|---|---|
| response_type | Y | Set to code |
|
| client_id | Y | the client id | |
| scope | N | A space separated list of scopes that have been approved for the API Authorization client. These scopes will be included in the Access Token that is returned. | |
| redirect_url | Y | The URL where the authentication server redirects the browser after the user is authorised. | |
| code_challenge_method | N | Set to S256 if using PKCE |
|
| code_challenge | N | the code challenge |
POST <%= I18n.t(:oidcHost) %>/oauth2/token
Header Parameters:
| Parameter | Mandatory | Default | Description |
|---|---|---|---|
| Authorization | N | base64 encoded <clientId>:<clientSecret>. Not required for authenticating public clients. |
|
| Content-Type | Y | application/x-www-form-urlencoded |
Request Parameters:
| Parameter | Mandatory | Default | Description |
|---|---|---|---|
| grant_type | Y | Set to authorization_code |
|
| code | Y | The authentication code returned from the authentication step | |
| redirect_url | Y | The URL where the authentication server redirects the browser after the user is authorised. | |
| code_verifier | N | the code challenge if using PKCE |
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 <%= I18n.t(:oidcHost) %>/oauth2/authorize
Request Parameters:
| Parameter | Mandatory | Default | Description |
|---|---|---|---|
| response_type | Y | Set to token |
|
| client_id | Y | the client id | |
| scope | N | A space separated list of scopes that have been approved for the API Authorization client. These scopes will be included in the Access Token that is returned. | |
| redirect_url | Y | The URL where the authentication server redirects the browser after the user is authorised. |
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 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
Interact with ALA data quality filters.
Explore interactively on the ALA Data Quality Filter Service app.
For full api documentation see Open API specification
Generate DOIs for ALA applications.
Explore interactively on the ALA DOI app.
For full api documentation see Open API specification
Interact with the ALA Logger Logger webapp, such as getting event types and reason breakdowns.
For full api documentation see Open API specification
Services for the MERIT and BioCollect applications.
For full api documentation see Open API specification
Access the ALA Events app.
For full api documentation see Open API specification
Access the ALA fieldguide service.
For full api documentation see Open API specification
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
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
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
Access the ALA namematching service.
For full api documentation see Open API specification
Services for interacting species occurrence records.
Explore interactively on the ALA BioCache app.
For full api documentation see Open API specification
Examples:
Services for interacting with ALA Profile collections
Explore interactively on the ALA Profile collection app.
For full api documentation see Open API specification
Services for interacting with Sensitive Data Service.
ALA uses the sensitive service to generalise sensitive occurrences. Using ala-sensitive-data-client it will get a record report ALASDSServiceClient::report and apply each generalisation from ALASDSServiceClient::getGeneralisations with Generalisation::process to produce the generalised output. See pipelines code.
Explore interactively on the ALA sensitive service.
For full api documentation see Open API specification
Services for interacting with ALA Spatial services
Explore interactively on the ALA Spatial app.
For full api documentation see Open API specification
Services for species profile data.
Explore interactively on the ALA Biodiversity Information Explorer app.
For full api documentation see Open API specification
Interact with species lists , including get list details and create a list.
For full api documentation see Open API specification
Interact with the ALA BioCollect app, such as searching for projects, surveys and activities.
For full api documentation see Open API specification
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