GPML API

The GPML API uses OpenID connect for authentication.

Firstly, a user account is needed, if you don't have any, you'll need to access your flow instance first https://digital.gpmarinelitter.org/signup, then apply for an entity or join as and individual and complete the required user details to have your user account. Don't forget to validate your email, clicking in the confirmation link that will be sent to your inbox. After an admin has approved your request, you can continue the process below.

Explore existing endpoints

Here https://digital.gpmarinelitter.org/api/docs/index.html#/ you can find all the GPML rest api endpoints.

Authenticate your user account to get the ID_TOKEN

The ID_TOKEN is a token issued as a result of user authentication.

In the following http request call, to get the ID_TOKEN, replace <user-email> and <user-password> with your current user email and password.

curl -s \
     -d "client_id=mSuWoeUEN3Z8XWZMbUqiOIOHwdk0R6dm" \
     -d "username=<user-email>" \
     -d "password=<user-password>" \
     -d "grant_type=password" \
     -d "scope=openid email" \
     "https://unep-gpml.eu.auth0.com/oauth/token"

The response will have the following structure, including the ID_TOKEN

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "scope": "openid email ....",
    "id_token": "eyJ0eXAiOiJKV1Q....",
    "access_token": "eyJ0eXAiOiJ...."
}

Pay attention to the expires_in value too. In this previous example response, the ID_TOKEN will expire in 86400 seconds (24 Hours)

Using the ID_TOKEN to communicate with GPML API

The ID_TOKEN is the token that should be used in the Authorization header.

Below, there is an example showing how to include the ID_TOKEN in the http gpml-api call to fetch a list of approved stakeholders.

curl --header "Content-Type: application/json" \
     --header "Authorization: Bearer <ID_TOKEN>" \
     --request GET \
     --url "digital.marinelitter.org/api/stakeholder?page=1&limit=10&review-status=SUBMITTED"

Combining the two in one command

This shell command line assumes that you have jq tool installed. It's usually available in most Linux and BSD distributions and you can also get it from Homebrew and MacPorts for OSX/MAcOS.

env ID_TOKEN="$(curl --silent \
                  -d 'client_id=mSuWoeUEN3Z8XWZMbUqiOIOHwdk0R6dm' \
                  -d 'username=<user-email>' \
                  -d 'password=<user-password' \
                  -d 'grant_type=password' \
                  -d 'scope=openid email' \
                  'https://unep-gpml.eu.auth0.com/oauth/token' | jq -r .id_token)" \
    bash -c 'curl --silent \
                  --header "Content-Type: application/json" \
                  --header "Authorization: Bearer ${ID_TOKEN}" \
                  --request GET \
                  --url "https://digital.gpmarinelitter.org/api/stakeholder?page=1&limit=10&review-status=SUBMITTED"' | jq