Connect and extend
API keys
A long-lived credential for the machines that cannot sign in: CI runners, headless servers, and anything calling the Lineman API on your behalf.
When you need one
Your own machine does not need one. The command line signs in as you and keeps its own token. An API key is for the places where nobody is present to click anything: a build agent, a scheduled job, a service calling the API.
A key belongs to the person who made it and carries their access. Issue one per system rather than sharing a single key around, or the day you have to revoke one you will take out everything at once.
Which person that is decides more than access: reports read through the API are scoped to the key's owner. A key made by an administrator or an auditor reads company-wide savings, and a key made by anyone else reads that person's own. Reissuing a key under a different name can therefore change what a report says without the request changing at all.
Creating a key
Keys are created from your account settings. You are shown the value once, at creation, and never again. Copy it into your secret store then, not later.
Put it wherever your other secrets live and reference it from there. A key pasted into a CI config file is a key in your git history.
Rotating and revoking
Revoking a key stops it working immediately, everywhere. There is no grace period, which is the point: a key you suspect is the one you should revoke now and replace afterwards.
To rotate without downtime, create the new key first, deploy it, then revoke the old one. Doing it the other way round means a window where the job is running with nothing valid.
Using a key
Send it as a bearer token: Authorization: Bearer YOUR_KEY. That is the same header the partner API expects, so a key that works against one endpoint works against all of them your account can reach.