Update README for new access key and URL settings (#457)

Finalizes #338. Related to #455, #468.

Author: gabrielfeo

README.md

@@ -28,12 +28,31 @@ This library [fixes][34] those issues in generated code, implements [paging][24]
 
 ## Setup
 
-Set up environment variables and use the library from any notebook, script or project:
+Set up once and use the library from any notebook, script or project:
 
-- [`DEVELOCITY_API_URL`][16]: the URL of your Develocity instance
-- [`DEVELOCITY_API_TOKEN`][17]: an [access key][31] for the Develocity instance
+- [`DEVELOCITY_URL`][16]: the URL of your Develocity instance
 - [`DEVELOCITY_API_CACHE_ENABLED`][12] (optional, off by default): enables caching for some
   requests (see [caveats][13])
+- An access key in one of the supported locations
+
+<details>
+
+<summary>Supported access key locations</summary>
+
+Access key support matches that of official tooling: the  Develocity [Gradle Plugin][37] and [Maven Extension][38].
+If you've already provisioned a key for your build to connect to Develocity, there's probably no action needed.
+Supported locations, in order of precedence:
+
+- a provider function as [`Config.accessKey`][17] (see [optional setup](#optional-setup))
+- official tooling locations with value in format `host=key`, e.g. `DEVELOCITY_ACCESS_KEY='foo.com=my-key'`:
+  - [`DEVELOCITY_ACCESS_KEY`](https://docs.gradle.com/develocity/gradle-plugin/current/#manual_access_key_configuration)
+  - [`GRADLE_ENTERPRISE_ACCESS_KEY`](https://docs.gradle.com/develocity/gradle-plugin/current/#manual_access_key_configuration)
+  - File `$GRADLE_USER_HOME/.gradle/develocity/keys.properties`, or `~/.gradle/develocity/keys.properties` if `GRADLE_USER_HOME` is not set
+  - File `~/.m2/.develocity/keys.properties`
+
+Refer to the Develocity [Gradle Plugin User Manual][37] or [Maven Extension User Manual][38] for details on these variables and files, including support for keys of multiple hosts.
+
+</details>
 
 ### Setup snippets
 
@@ -177,8 +196,8 @@ your own. For example:
 
 ```kotlin
 val config = Config(
-  apiUrl = "https://ge.mycompany.com/api/",
-  apiToken = { vault.getGeApiToken() },
+  develocityUrl = "https://ge.mycompany.com/",
+  accessKey = { vault.getDevelocityAccessKey() },
   clientBuilder = existingClient.newBuilder(),
 )
 val api = DevelocityApi.newInstance(config)
@@ -219,8 +238,8 @@ For general discussions or questions, feel free to reach out to maintainers on t
 [12]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/-cache-config/cache-enabled.html
 [13]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/-cache-config/index.html
 [14]: https://central.sonatype.com/artifact/com.gabrielfeo/develocity-api-kotlin/2024.3.0
-[16]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/api-url.html
-[17]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/api-token.html
+[16]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/server.html
+[17]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-config/access-key.html
 [18]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/index.html
 [19]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api.model/-gradle-attributes/index.html
 [20]: https://gabrielfeo.github.io/develocity-api-kotlin/library/com.gabrielfeo.develocity.api/-builds-api/index.html
@@ -240,3 +259,5 @@ For general discussions or questions, feel free to reach out to maintainers on t
 [34]: https://github.com/gabrielfeo/develocity-api-kotlin/blob/main/build-logic/src/functionalTest/kotlin/com/gabrielfeo/task/PostProcessGeneratedApiTest.kt#L21
 [35]: https://community.gradle.org/#community-channels
 [36]: ./examples/example-gradle-task/
+[37]: https://docs.gradle.com/develocity/gradle-plugin/current/#manual_access_key_configuration
+[38]: https://docs.gradle.com/develocity/maven-extension/current/#manual_access_key_configuration

docs/AccessKeys.md

@@ -1,32 +1,43 @@
-# Access key / API token
+# Access keys
 
-[All API requests require authentication][1]. Provide a valid access key of your Develocity instance
-as the `DEVELOCITY_API_TOKEN` environment variable.
+API requests may require [authentication][1].
 
-## How to get an access key
+## Anonymous access
 
-1. Sign in to Develocity (with a user that has “Export build data” permission)
-2. Go to "My settings" from the user menu in the top right-hand corner of the page
-3. Go to "Access keys" from the sidebar
-4. Click "Generate" on the right-hand side
-5. Set key as the `DEVELOCITY_API_TOKEN` environment variable when using the library
+If your Develocity server is configured to allow [anonymous access][2] for permission "Access build data via the API", then an access key is not required to use this library.
+This is often the case for a server only accessible from a private network.
 
-## Migrating from macOS keychain support
+![Anonymous access settings](media/AnonymousAccessPage.png)
 
-This library used to support storing the key in the macOS keychain as `gradle-enterprise-api-kotlin`.
-This feature was deprecated in 2023.4.0, then removed in 2024.1.1. You may use the method of your choice
-(secret managers, password manager CLIs, etc.) to store and retrieve the key to an environment.
+## Authenticated access
 
-If you used the key from keychain and need a drop-in replacement:
+The library will automatically resolve the access key using the same conventions as official Develocity tooling, in order:
 
-```
-# Create an alias in your shell to fetch the key from keychain
-echo 'alias dat="security find-generic-password -w -a "$LOGNAME" -s gradle-enterprise-api-kotlin"' >> ~/.zshrc
+- Environment variable `DEVELOCITY_ACCESS_KEY`
+- Environment variable `GRADLE_ENTERPRISE_ACCESS_KEY`
+- File `$GRADLE_USER_HOME/.gradle/develocity/keys.properties` (or `~/.gradle/develocity/keys.properties` if `GRADLE_USER_HOME` is not set)
+- File `~/.m2/.develocity/keys.properties`
 
-# Retrieve it to the environment variable before running the program
-DEVELOCITY_API_TOKEN="$(dat)" ./my-script.main.kts
-DEVELOCITY_API_TOKEN="$(dat)" jupyter lab
-DEVELOCITY_API_TOKEN="$(dat)" idea my-project
-```
+Please check if you already have an access key set up in your build environment for the Develocity server you want to query. The first key for a matching host will be used, if found.
+
+See the official manuals for instructions on how to set up a new access key in one of these locations:
+
+- [Develocity Gradle Plugin User Manual][3]
+- [Develocity Maven Extension User Manual][4]
+- [Develocity sbt Plugin User Manual][5]
+- [Develocity npm Agent User Manual][6]
+- [Develocity Python Agent User Manual][7]
+
+### User permissions
+
+To call the API, the user from which the access key was generated must have the "Access build data via the API" permission.
+
+![User permissions](media/AccessPage.png)
 
 [1]: https://docs.gradle.com/enterprise/api-manual/#access_control
+[2]: https://docs.gradle.com/develocity/helm-admin/current/#_anonymous_access
+[3]: https://docs.gradle.com/develocity/gradle-plugin/current/#manual_access_key_configuration
+[4]: https://docs.gradle.com/develocity/maven-extension/current/#manual_access_key_configuration
+[5]: https://gradle.com/help/sbt-plugin-authenticating
+[6]: https://gradle.com/help/npm-agent-authenticating
+[7]: https://gradle.com/help/python-agent-authenticating

docs/media/AccessPage.png

@@ -9,7 +9,7 @@
    "source": [
     "# Most frequent builds\n",
     "\n",
-    "See what builds are most commonly invoked by developers, e.g. `clean assemble`, `test` or `check`. You can [set up the URL and a token for your Develocity instance](https://github.com/gabrielfeo/develocity-api-kotlin/blob/main/README.md#setup) and run this notebook as-is for your own project.\n",
+    "See what builds are most commonly invoked by developers, e.g. `clean assemble`, `test` or `check`. You can [set up the URL and an access key for your Develocity instance](https://github.com/gabrielfeo/develocity-api-kotlin/blob/main/README.md#setup) and run this notebook as-is for your own project.\n",
     "\n",
     "This is a simple example of something you can do with the API. It could bring insights, for example:\n",
     "\n",