Getting started / Authentication

Getting started

Authentication

API keys, how to send them, and what they can do.

Every request to /api/v1 is authenticated with an API key sent as a bearer token:

http
GET /api/v1/whoami HTTP/1.1
Authorization: Bearer gp_32bdfe84998d44a26_…

API keys#

Create keys under API keys in the dashboard. A key:

  • belongs to the organization you're working in when you create it, not to you. It can see and change everything that organization owns: binaries, profiles and jobs.
  • stops working if you leave the organization or are removed from it. In an organization, anyone can revoke their own keys, and owners and admins can revoke anyone's.
  • is shown once, when it's created. GuardPkg stores only a hash, so a lost key can't be recovered; revoke it and create a new one.
  • looks like gp_<16 hex characters>_<secret>. The first part (the prefix) is shown in the dashboard so you can tell keys apart.
  • records when it was last used, so you can spot keys that are no longer needed.

Use one key per pipeline or machine, and give each a name that says where it's used (ci-release, build-agent-02). Revoking a key takes effect immediately.

Checking a key#

GET /api/v1/whoami returns the key and the organization a request is acting as:

bash
curl -H "Authorization: Bearer $GUARDPKG_KEY" "$GUARDPKG_URL/api/v1/whoami"
json
{"key_id": "01a19951-b051-78dc-bdfe-10dc21fedf29", "key_name": "ci-release", "org_id": "01a19951-b020-7d74-a326-d5f7af05b789", "org_name": "Acme Security"}

Failures#

Status Body Meaning
401 {"error": "missing bearer token"} No Authorization: Bearer … header.
401 {"error": "invalid api key"} The key doesn't exist, was revoked, or has expired.

Keep keys out of source control and build logs. Most CI systems have a secret store that exposes secrets as environment variables, which is what the examples in these docs assume ($GUARDPKG_KEY).