Create an API key for your workspace
Create a service account and an API key so an app, script, or integration can call the workspace API.
This guide shows you how to create an API key your application can use to send traces, run evaluations, or read data from a workspace.
API keys belong to service accounts, the non-human principals that authenticate workspace API traffic. You create a service account, choose what it can do, and then issue one or more API keys for it. For background on the role system, see Roles and permissions.
Prerequisites
- A Blue Guardrails account
- A workspace role of Contributor or Admin in the target workspace
- The permissions you want the API key to hold (you can only grant permissions you hold yourself)
Create a service account
Requires workspace role: Contributor or Admin
- Click Workspaces in the sidebar.
- Click the workspace you want to create the key for.
- Open the Service accounts tab.
- Click Create service account.
- Enter a name (for example,
Production traces). - Choose a permission preset that matches the use case, or expand Custom permissions to pick individual permissions.
- Click Create.
The new service account appears in the table with zero API keys.
Permission presets
Pick the smallest preset that fits the use case. Each preset only enables if you hold every permission it contains.
| Preset | Use it for |
|---|---|
| Trace writer | Sending traces from your application |
| Read-only | Dashboards or reports that read workspace data |
| Read + trace writer | Apps that send traces and read back data |
| Evaluation runner | Running issue detection on existing data |
| Experiment runner | Reading data and running model comparison experiments |
| Experiment operator | Read, run, and clean up experiments |
If no preset fits, use Custom permissions and select the exact permissions you need.
Create an API key
Admins can create keys for any service account in the workspace. Contributors can create keys for service accounts they created themselves.
- Find the service account in the Service accounts tab.
- Click Create key in the API keys column, or open the actions menu and click Create API key.
- Enter a name for the key (for example,
Production ingest key). - Pick an expiration: 7, 30, 60, 90, 180, or 365 days.
- Click Create.
Blue Guardrails shows the full key one time. Copy it now and store it in a secret manager. You can't view it again after closing the dialog. If you lose it, delete the key and create a new one.
Use the API key
Send the key in the Authorization header on every request. The key already identifies the workspace, so you don't need to pass a workspace ID:
curl https://api.blueguardrails.com/v1/traces \
-H "Authorization: Bearer $BLUE_GUARDRAILS_API_KEY" \
-H "Content-Type: application/x-protobuf" \
--data-binary @traces.pbThe key resolves to its service account on every call. Requests that need a permission the service account doesn't hold return 403 Forbidden.
Rotate or revoke a key
To rotate, create a new key, deploy it, and then delete the old one:
- Open the Service accounts tab and expand the service account.
- In the API keys list, click Delete key on the key you want to revoke.
- Confirm the deletion.
Deleted keys stop working immediately. Any client still using the key gets 401 Unauthorized on the next request.
Delete a service account
If you no longer need a service account, delete it instead of leaving stale keys:
- Open the actions menu on the service account's row.
- Click Delete service account.
- Confirm the deletion.
This deletes every API key for the service account. Existing integrations using those keys stop working.