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:
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:
curl -H "Authorization: Bearer $GUARDPKG_KEY" "$GUARDPKG_URL/api/v1/whoami"
{"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).