Authentication

Most API endpoints require a signed-in user. You authenticate in one of two ways:

1. An API token sent as a Bearer token in the Authorization header. Recommended for scripts and integrations.
2. A session cookie, the same one the browser uses after you sign in.

The API returns 401 with {"error": "Authentication required"} when neither is present, and {"error": "Invalid or expired token"} when a Bearer token does not validate.

Create an API token

1. Sign in to Malva with your ORCID account.
2. Open your profile page.
3. In the API token section, click Generate token.
4. Copy the token, shown once, and store it in a safe place. It starts with malva_ and is not shown again.

You can revoke a token from the same section at any time. Revocation takes effect immediately for new requests.

See Account and API tokens for details.

Send the token

Add the token as a Bearer token in the Authorization header:

curl -X POST https://malva.mdc-berlin.de/api/expression/submit \
  -H "Authorization: Bearer malva_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "CD3E MS4A1"}'

In Python with requests:

import requests

headers = {"Authorization": "Bearer malva_..."}
r = requests.post(
    "https://malva.mdc-berlin.de/api/expression/submit",
    headers=headers,
    json={"query": "CD3E MS4A1"},
)
print(r.json())

The malva_client package stores the token for you and sends it on every request. See Python client.

Check that a token works

curl https://malva.mdc-berlin.de/api/expression/quota \
  -H "Authorization: Bearer malva_..."

{"can_search": true, "searches_remaining": 48, "account_type": "free"}

The /api/expression/quota and /api/quota-status endpoints return your remaining daily quota. GET /health is public and returns the service status without authentication.

Browser session

When you sign in through the browser, Flask-Login sets a session cookie that the same auth_required checks accept. Any HTTP client that keeps cookies (for example requests.Session) can use a session instead of a Bearer token. Scripts should normally use a token, because it does not expire with the session.

CSRF

The API endpoints are exempt from CSRF protection, so no CSRF token is needed. The exception is the account management forms in the browser (POST /token-login, POST /generate-api-token, and the profile forms), which require a CSRF token because they are browser forms, not API endpoints.

Related endpoints

Endpoint	Purpose
GET /api/expression/quota	Remaining daily quota for the current user
GET /api/quota-status	Same data, compatibility route used by malva_client
GET /health	Public service health, used to test a connection