Authenticating via API

Some of our endpoints require authentication in order to use them. In order to use these endpoints you need to get a JSON web token. You can obtain the token either by sending a request to our Keycloak authentication server or by retrieving the corresponding cookie from the browser.

The retrieved token expires after 10 hours.

Send request with cURL

To use the demo instance instead of the main instance, please replace authentication.pathoplexus.org with authentication-demo.pathoplexus.org.

The following script demonstrates how you can retrieve a token with a POST request using cURL. It only works if you use a simple username-password authentication. If you only use ORCiD for authentication and do not have a password, you need to add a password (see how to edit your account). This solution also does not work if you activated two-factor authentication. In these cases, you can retrieve a token from the browser (see section below).

KEYCLOAK_TOKEN_URL="https://authentication.pathoplexus.org/realms/loculus/protocol/openid-connect/token"
KEYCLOAK_CLIENT_ID="backend-client"

USERNAME_LOCULUS="MY_USERNAME_HERE"
PASSWORD_LOCULUS="MY_PASSWORD_HERE"

jwt_keycloak=$(curl -X POST "$KEYCLOAK_TOKEN_URL" --fail-with-body -H 'Content-Type: application/x-www-form-urlencoded' -d "username=$USERNAME_LOCULUS&password=$PASSWORD_LOCULUS&grant_type=password&client_id=$KEYCLOAK_CLIENT_ID")
jwt=$(echo "$jwt_keycloak" | jq -r '.access_token')

echo "$jwt"

Retrieve token from browser

After you have logged in on pathoplexus.org (or demo.pathoplexus.org for the demo instance), an access token is stored in your browser as a cookie. The token is called access_token and you can manually retrieve it from the browser. Instructions on how to do it can be found in the documentation of the browsers: Google Chrome, Firefox and Safari.