API Keys
Create, manage, and revoke API keys for programmatic access to the ProBeya API.
Overview
API keys provide programmatic access to the ProBeya API for integrations, scripts, and automated workflows. Each key is scoped to a specific organization and can be restricted with permission scopes and expiration dates.
API keys follow the format: probeya_sk_live_{40 hex characters}.
Creating an API Key
Open API Key Settings
Navigate to Settings > API Keys in your organization admin panel.
Click Create Key
Click the Create API Key button to open the creation dialog.
Configure the Key
Fill in the following fields:
- Name — a human-readable label to identify this key (e.g., “CI/CD Pipeline”, “iOS App”, “Data Sync Script”)
- Scopes — optional permission restrictions. Leave empty for full access, or select specific scopes to limit what the key can do.
- Expiration — optional expiration date. After this date, the key is automatically rejected.
Copy the Key
After creation, the full API key is displayed once. Copy it immediately and store it securely (e.g., in a secrets manager or environment variable).
The full API key is shown only at creation time. It cannot be retrieved later. If you lose the key, you must revoke it and create a new one.
Security Architecture
ProBeya uses a security model inspired by major API providers (Stripe, GitHub):
| Component | Details |
|---|---|
| Key format | probeya_sk_live_ prefix + 40 random hex characters (160 bits of entropy) |
| Storage | Only the bcrypt hash is stored in the database — the plaintext key is never persisted |
| Lookup | The first 8 hex characters serve as a prefix for efficient database lookup |
| Verification | Full key is verified against the bcrypt hash using bcrypt.compare() |
| Salt rounds | 10 rounds of bcrypt salting |
This means that even if the database is compromised, API keys cannot be recovered from the stored hashes.
Using an API Key
Include the API key in the Authorization header of your HTTP requests:
curl -H "Authorization: Bearer probeya_sk_live_a1b2c3d4..." \
https://acme.probeya.com/api/v1/items
The API validates the key by:
- Extracting the prefix (first 8 hex chars after
probeya_sk_live_) - Looking up the key record by prefix and organization
- Comparing the full key against the stored bcrypt hash
- Checking expiration date and revocation status
- Verifying the requested operation against the key’s scopes
Managing Keys
Listing Keys
The API Keys settings page displays all keys for your organization with:
- Key name and prefix (for identification)
- Creation date
- Last used date
- Expiration date (if set)
- Status (active or revoked)
Revoking a Key
To revoke a key, click the Revoke button next to the key in the settings page. Revocation is irreversible — once revoked, a key cannot be reactivated. Any API request using a revoked key will receive a 401 Unauthorized response.
Deleting a Key
Revoked keys can be deleted to remove them from the list entirely. Active keys must be revoked before they can be deleted.
Permission Scopes
Scopes restrict what an API key can access. When no scopes are set, the key has full access to all API endpoints within the organization.
| Scope | Allows |
|---|---|
items:read | Read items, boards, and groups |
items:write | Create, update, and delete items |
kpis:read | Read KPI definitions and values |
kpis:write | Record KPI values |
actions:read | Read actions and checklists |
actions:write | Create and update actions |
members:read | List organization members |
webhooks:manage | Create, update, and delete webhooks |
Best Practices
- Use descriptive names — name each key after its purpose (e.g., “GitHub Actions CI” or “Power BI Connector”) so you can identify keys at a glance.
- Set expiration dates — avoid indefinite keys. Rotate keys on a regular schedule (e.g., every 90 days).
- Use minimal scopes — only grant the permissions the integration actually needs.
- Never commit keys to source code — store them in environment variables or a secrets manager.
- Revoke unused keys — regularly audit your API keys and revoke any that are no longer in use.
API key management can only be performed through the web UI with an active session. You cannot create or revoke API keys using another API key — this prevents privilege escalation.
Rate Limits
API key requests are subject to the same rate limits as session-based requests. The default limit is 1000 requests per minute per organization. Enterprise plans support higher limits.