Update README and examples

Author: gabrielfeo

README.md

@@ -27,12 +27,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_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][36] and [Maven Extension][37].
+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][36] or [Maven Extension User Manual][37] for details on these variables and files, including support for keys of multiple hosts.
+
+</details>
 
 ### Setup snippets
 
@@ -171,7 +190,7 @@ your own. For example:
 ```kotlin
 val config = Config(
   apiUrl = "https://ge.mycompany.com/api/",
-  apiToken = { vault.getGeApiToken() },
+  accessKey = { vault.getDevelocityAccessKey() },
   clientBuilder = existingClient.newBuilder(),
 )
 val api = DevelocityApi.newInstance(config)
@@ -213,7 +232,7 @@ For general discussions or questions, feel free to reach out to maintainers on t
 [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
+[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
@@ -232,3 +251,5 @@ For general discussions or questions, feel free to reach out to maintainers on t
 [33]: https://github.com/gradle/develocity-api-samples
 [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]: https://docs.gradle.com/develocity/gradle-plugin/current/#manual_access_key_configuration
+[37]: https://docs.gradle.com/develocity/maven-extension/current/#manual_access_key_configuration

examples/example-notebooks/MostFrequentBuilds.ipynb

@@ -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",