Whilst working on bug 1032163 there were a few things I spotted in the docs that could be tweaked to avoid confusion, so making a note of these here. * Whilst on https://docs.taskcluster.net/reference/platform/auth/api-docs , it wasn't clear how one should authenticate with the various APIs. It would be great to add an entry to the table of contents for the 'Reference' section that covers Hawk authentication, what headers to set etc (or just linking to https://docs.taskcluster.net/manual/apis if that's the most appropriate place - I just didn't see that straight away, since it was in the 'Manual' section rather than 'Reference') * https://docs.taskcluster.net/manual/apis mentions that the clientId and accessToken are used with Hawk but doesn't go into details. Is accessToken the hawk parameter called 'key'? ie there's more details on temporary credentials (on https://docs.taskcluster.net/manual/apis/temporary-credentials) than there are on 'normal' credentials. The answer here might just be to use the official clients - if so, perhaps we should explicitly state that the official clients should be used. * On https://docs.taskcluster.net/manual/apis/temporary-credentials the attribute `temporaryAccessToken` is mentioned several times, however the response from login.taskcluster.net (which are supposedly temporary credentials) instead still uses the attribute `accessToken`. Should the docs actually be referring to: 'temporary `accessToken`' ...rather than: '`temporaryAccessToken`' ? * On https://docs.taskcluster.net/manual/apis it mentions that credentials are 'sometimes' accompanied by a certificate, is this just for temporary credentials? If so, it would be good to state that. (https://docs.taskcluster.net/manual/apis/temporary-credentials would imply so). * On https://docs.taskcluster.net/manual/apis/temporary-credentials it says: "A set of temporary credentials cannot be used to issue new temporary credentials" ...and then on https://github.com/taskcluster/taskcluster-login/blob/master/README.md : "This service provides a very minimal UI that users can authenticate against and then get temporary credentials issued." ...however the scopes returned in the certificate generated on https://login.taskcluster.net/ , includes: auth:create-client:mozilla-ldap/emorley@mozilla.com/* ...which seems to contradict the "cannot create new credentials"? * New temporary credentials generated by https://login.taskcluster.net/ don't appear on https://tools.taskcluster.net/auth/clients/ . Presuming this is expected, it would be good to mention that on https://docs.taskcluster.net/manual/apis/clients and likely also on the Client Manager tool page too. Side note: how does one go about seeing what temporary credentials are active? Or is that not possible? * Reading https://docs.taskcluster.net/reference/platform/auth/api-docs it's not clear which endpoint I should be using to verify the callback generated from eg https://login.taskcluster.net/?target=https://treeherder.mozilla.org/&description=Treeherder . The first one that stood out was https://docs.taskcluster.net/reference/platform/auth/api-docs#authenticateHawk however that operates on a provided URL, which isn't what we want. The other I guess is https://docs.taskcluster.net/reference/platform/auth/api-docs#currentScopes where we can both check the validity of the user's accessToken, and also retrieve the expanded list of scopes. Perhaps the recommended endpoint could be mentioned on https://github.com/taskcluster/taskcluster-login/blob/master/README.md#access-grant-for-tools

I'm happy to open some PRs for these once I have a better understanding of the above :-)

* On https://github.com/taskcluster/taskcluster-client.py#methods-in-taskclusterauth there's: ``` // Create Auth client instance import taskcluster auth = taskcluster.Auth(options) ``` ...however it's not really explained anywhere what `options` should (or can) contain. By experimentation I found that it should be the credentials, but it would be good to mention this explicitly. (In reply to Ed Morley [:emorley] from comment #0) > * New temporary credentials generated by https://login.taskcluster.net/ > don't appear on https://tools.taskcluster.net/auth/clients/ . Presuming this > is expected, it would be good to mention that on > https://docs.taskcluster.net/manual/apis/clients and likely also on the > Client Manager tool page too. Side note: how does one go about seeing what > temporary credentials are active? Or is that not possible? Similarly, the python client gives: >>> auth.client('mozilla-ldap/emorley@mozilla.com') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/home/Ed/.virtualenvs/tc/lib/python2.7/site-packages/taskcluster/sync/Auth.py", line 119, in client return self.makeHttpRequest('get', route) File "/home/Ed/.virtualenvs/tc/lib/python2.7/site-packages/taskcluster/sync/syncclient.py", line 60, in makeHttpRequest return self._makeHttpRequest(method, url, payload, headers) File "/home/Ed/.virtualenvs/tc/lib/python2.7/site-packages/taskcluster/sync/syncclient.py", line 92, in _makeHttpRequest self._raiseHttpError(status, data, rerr) File "/home/Ed/.virtualenvs/tc/lib/python2.7/site-packages/taskcluster/baseclient.py", line 337, in _raiseHttpError superExc=rerr taskcluster.exceptions.TaskclusterRestFailure: Client not found! - { "message": "Client not found!" }

> ...which seems to contradict the "cannot create new credentials"? it can create new credentials, just not *temporary* credentials.

> Side note: how does one go about seeing what temporary credentials are active? Or is that not possible? No, temp credentials are entirely ephemeral and can't be listed or seen anywhere. Regarding the client docs, I have plans to fold those into the docs site, rather than leaving them in READMEs, at which point I'll better define `options` and the like.

Commits pushed to master at https://github.com/taskcluster/taskcluster-docs https://github.com/taskcluster/taskcluster-docs/commit/0b956f88c10e4cdc2ee4a3dd026a03971ec3e50a Bug 1272995: remove headings from some reference pages, split api-docs and exchanges https://github.com/taskcluster/taskcluster-docs/commit/75e25fa87106e6aa641bfd4d34d6e4b7c67e8c56 Bug 1272995: include links to 'Using the APIs' in each api doc https://github.com/taskcluster/taskcluster-docs/commit/f38aff5b3d61708e5c63473f48114cb172616caa Bug 1272995: expand on basic credential usage https://github.com/taskcluster/taskcluster-docs/commit/104a3c6037d9c6f28368c01a2290e94323e03e68 Bug 1272995: describe named temporary creds by default, anonymous as an option https://github.com/taskcluster/taskcluster-docs/commit/8663f7d790a1272ec06c92f9412f0b47fd0f5a4c Merge djmitche/taskcluster-docs:bug1272995 (PR #96)

Thank you for these changes - they help a lot. (In reply to Dustin J. Mitchell [:dustin] from comment #4) > No, temp credentials are entirely ephemeral and can't be listed or seen > anywhere. Ah that was the piece I was missing. I initially thought temporary credentials were just standard credentials with a subset of scope and also an expiry time, but I see they are really 'standalone credentials', which explains the signature.