How does an Etherpad client learn the server's api key?

Question

I'm trying to access an Etherpad from a Java application. The ultimate goal is to link an existing editor (BlueJ's Java editor) to a pad so students can collaborate within the BlueJ editor while working on Java exercises. I'm not hosting the pad myself -- I'd like to use a publicly available Etherpad instead (because students will, too).

I found a Java implementation of the low-level client-side Etherpad protocol at https://github.com/nilsfr/java-etherpad-lite that I'm trying to build on. It provides the following example:

EPLiteClient client = new EPLiteClient("http://localhost:9001", "K8OF91QMQYUvrNu3e9rJ7FnnVgaB3m9q");

// Create pad and set text
client.createPad("my_pad");
client.setText("my_pad", "foo!!");

// Get pad text
String text = client.getText("my_pad").get("text").toString();

// Get list of all pad ids
Map result = client.listAllPads();
List padIds = (List) result.get("padIDs");

Obviously, one needs to know the server-side api key (constructor call in the first line of the example, second argument). When I try the example with an arbitrary or empty API key, the server returns a HTTP status code of 405 or 401, depending on the exact URL used.

I tried accessing the pad with curl instead of Java:

me@computer: curl -vi "https://pad.piratensommer.de/api/1.2.13/setText?apikey=&padId=bethpad-test" --get --data-urlencode "text=example"
*   Trying 2a01:4f8:211:1405::3030:443...
* TCP_NODELAY set
* Connected to pad.piratensommer.de (2a01:4f8:211:1405::3030) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*   CAfile: /etc/ssl/certs/ca-certificates.crt
  CApath: /etc/ssl/certs
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
* TLSv1.3 (IN), TLS handshake, Finished (20):
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
* ALPN, server accepted to use http/1.1
* Server certificate:
*  subject: CN=pad.piratensommer.de
*  start date: Nov 17 18:06:54 2021 GMT
*  expire date: Feb 15 18:06:53 2022 GMT
*  subjectAltName: host "pad.piratensommer.de" matched cert's "pad.piratensommer.de"
*  issuer: C=US; O=Let's Encrypt; CN=R3
*  SSL certificate verify ok.
> GET /api/1.2.13/setText?apikey=&padId=bethpad-test&text=example HTTP/1.1
> Host: pad.piratensommer.de
> User-Agent: curl/7.68.0
> Accept: */*
> 
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* old SSL session ID is stale, removing
* Mark bundle as not supporting multiuse
< HTTP/1.1 401 Unauthorized
HTTP/1.1 401 Unauthorized
< Date: Sun, 09 Jan 2022 21:37:08 GMT
Date: Sun, 09 Jan 2022 21:37:08 GMT
< Server: Apache/2.4.29 (Ubuntu)
Server: Apache/2.4.29 (Ubuntu)
< X-Powered-By: Express
X-Powered-By: Express
< X-UA-Compatible: IE=Edge,chrome=1
X-UA-Compatible: IE=Edge,chrome=1
< Referrer-Policy: same-origin
Referrer-Policy: same-origin
< Content-Type: application/json; charset=utf-8
Content-Type: application/json; charset=utf-8
< Content-Length: 54
Content-Length: 54
< ETag: W/"36-dbJd0O+vdNi3zPpwRXE+1EGLTho"
ETag: W/"36-dbJd0O+vdNi3zPpwRXE+1EGLTho"
< Set-Cookie: express_sid=s%3A05JnHPsNQe1IjdbJZ-amku0rMquAdHW_.WLoGsw9twT3ZRSh2CWfi1afJY5%2FejwZdIqgh%2BQpYpnE; Path=/; HttpOnly; SameSite=None
Set-Cookie: express_sid=s%3A05JnHPsNQe1IjdbJZ-amku0rMquAdHW_.WLoGsw9twT3ZRSh2CWfi1afJY5%2FejwZdIqgh%2BQpYpnE; Path=/; HttpOnly; SameSite=None
< Via: 1.1 pad.piratensommer.de
Via: 1.1 pad.piratensommer.de

< 
* Connection #0 to host pad.piratensommer.de left intact
{"code":4,"message":"no or wrong API Key","data":null}

The most relevant line is obviously the last one, proving I am talking to the Etherpad server, but not allowed to connect (sorry for the long output, I thought the the "curl -v" verbose output might be helpful to some).

Question 1: Is there a way to know or learn the server's API key? On the one hand there shouldn't be, as that key is supposed to be secret. On the other hand, pads can be shared by simple links, so servers do accept HTTP clients that don't know the API key (yet), at least browser-based clients.

Question 2: So I'm wondering how the "normal" Etherpad page connects to the server if the user simply types in a link, but no api key?

Question 3: Is there a different way of connecting to an Etherpad server (when I'm not hosting it myself), that I'm not aware of?

Question 4: The Etherpad HTTP/JSON API documentation at https://etherpad.org/doc/v1.8.4/#index_authentication contains the sentences "Only Etherpad and the requesting application knows this key. Token management will not be exposed through this API." What exactly does the second sentence mean?

Question 5: The Java client implementation mentioned above is surprisingly old, but seems to be the best one I could find. Does anybody know what library people are using to connect to Etherpads from Java?

Thanks for any help, or pointers to help!

Edited to add: The bug report discussion at https://github.com/ether/etherpad-lite/issues/284 suggests that it shouldn't be too hard to extract the API key from HTTP requests, but I don't see how. So my question 6 is: How do I do that?

Answer 1

According to the docs

There is a single token per Etherpad deployment. This token will be random string, generated by Etherpad at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad.

Even If you are not having your own instance for Etherpad running you need the APIKEYs.