Clarity on Agent Access Token Scope

[abhishekmukherg]

Hey! I was hoping to get some clarity on Scope of Access. In the doc, it describes that an agent access token can be used to register an agent to a queue. What else can it (or the session token) do? Can it

• Arbitrarily set meta-data on any job?
• Arbitrarily upload artifacts to any job?
• Upload additional steps to any job, or just those that are already given to it?
• None of these things?

Thanks!

[abhishekmukherg]

One more I have interest in is if an agent token can enable a process to write to the stdout of a job -- for example, it's not clear to me if log streaming is effectively locked to an existing TCP socket, and if there's any reconnection logic

[plaindocs]

Hi @abhishekmukherg I took a look at this, and dug a bit further.

• Agent tokens (aka agent registration tokens): You get a default agent registration token when you create an organization and are what you can access and create yourself in the web UI. They are used to start an agent, and can't be used with the artifact, meta-data, ... These are not exposed to running jobs
• Agent access tokens (aka agent session tokens): these ones are created when an agent is registered with Buildkite, and are unique for every registered agent, i.e. when buildkite-agent start --token=$AGENT_REGISTRATION_TOKEN is run. It will only work for as long as that agent is running, and is used by all agent operations once the agent is started/registered. The access token is exposed within the job environment.

Does this answer you question?

I'll update and consolidate the docs so that this is all easier to find in the meantime.

[abhishekmukherg]

Hi! I think that answers the majority of my questions. Just a couple clarifying ones though that I think the docs could benefit from clarity on:

• Am I understanding correctly that, given an Agent Registration Token, one could trade the Registration Token for a Session Token (without any additional check)?
• Does a session token grant read/write access for the things it can do to all jobs/pipelines? Or is it scoped to the job that the agent is currently running?

Thanks!

[moskyb]

hi there @abhishekmukherg! i can answer some of your questions.

could one trade the Registration Token for a Session Token?

yep. the way the agent does this is that it calls the https://agent.buildkite.com/v3/register endpoint with its registration token in the authorization header, and that API response is an agent access token that has permission to do agenty things. The agent then ingests the agent access token from this response, and uses it to do agenty things from then on.

Does a session token grant read/write access for the things it can do to all jobs/pipelines?

i believe so, yes. agents can be long-running, so they might get launched to service one pipeline, but might pick up work for another after the first one is done, so they need access to all pipelines/jobs. feel free to correct me if i'm wrong here though @plaindocs! i'm pretty new 😅

can an agent token enable a process to write to the stdout of a job?

also yes. job log streaming happens on the https://agent.buildkite.com/v3/jobs/chunks agent api endpoint, which is authenticated using the agent access token. the result of this is that if a bad actor had access to your agent access token, they could write bad logs, but they can't remove any logs. The endpoint is append-only.