API Keys

Your integration team needs to connect ProBeya to your MES (Manufacturing Execution System), feed KPI data from your Historian, and sync action items with your corporate ServiceNow instance. API keys provide programmatic access for these integrations with the same security model used by GitHub Personal Access Tokens and Stripe API keys -- keys shown once, bcrypt-hashed storage, prefix-based lookup, and scoped permissions.

API access requires the Pro plan or higher (feature gate level 2).

API Key vs. OAuth vs. SSO: Choosing the Right Auth Model

Criterion	API Keys	OAuth 2.0 (SSO)	Session (Browser)
Best for	Server-to-server integrations, CI/CD, scripts	User-facing apps with delegated access	Interactive browser use
Credential type	Long-lived bearer token	Short-lived access token + refresh token	Session cookie
User context	Bound to the creating user	Bound to the authenticating user	Active session user
Scope control	Granular per-key scopes	Defined by OAuth scopes	Full user permissions
Rotation	Manual or scheduled	Automatic via refresh tokens	Automatic via session renewal
GxP audit trail	API key ID logged per request	User ID logged per request	User ID logged per action
Revocation	Immediate, irreversible	Token expiry + revocation endpoint	Session termination

Recommendation for Pharma Integrations

Use API keys for headless integrations (MES sync, LIMS data feed, CI/CD pipelines). Use SSO for interactive applications where a human user is present. Never embed API keys in client-side JavaScript or mobile app code.

Key Architecture

ProBeya API keys follow a defense-in-depth design:

Property	Value	Security Rationale
Format	probeya_sk_live_{40 hex chars}	Identifiable in logs and config files without exposing the secret
Entropy	160 bits (20 random bytes)	Exceeds NIST SP 800-132 recommendation of 128 bits
Storage	bcrypt hash (10 salt rounds)	Even if the database is compromised, plaintext keys cannot be recovered
Lookup	8-char hex prefix for DB query	Narrows search to ~1 row per prefix (out of ~4 billion possible prefixes)
Generation	crypto.randomBytes() (OS CSPRNG)	Cryptographically secure, backed by /dev/urandom on Linux
Visibility	Full key shown once at creation	Same pattern as Stripe, GitHub, AWS -- forces immediate secure storage

Available Scopes

Scopes restrict what an API key can access. An empty scope array means full access (all scopes granted).

Scope	Description	Pharma Use Case
read:items	Read items, boards, projects	MES dashboard pulling board status
write:items	Create, update, delete items	Automated deviation import from TrackWise
read:kpis	Read KPI definitions and values	Historian feeding data to analytics dashboard
write:kpis	Record KPI values, set targets	Automated OEE data ingestion from MES
read:actions	Read action items	ServiceNow integration pulling open actions
write:actions	Create, update action items	Automated CAPA creation from quality events
read:search	Execute search queries	Enterprise search integration
read:dashboard	Read dashboard statistics	Executive reporting portal
read:notifications	Read notifications	Mobile app notification feed

Getting Started

1. Navigate to Settings > API Keys.
2. Click Create API Key.
3. Enter a descriptive name (1--100 characters, e.g., "MES Integration - Brussels Site").
4. Select scopes to restrict permissions (leave empty for full access).
5. Optionally set an expiration date (ISO 8601 format).
6. Click Create and copy the key immediately -- it will not be shown again.

warning

API key management requires the manage_settings permission, which is restricted to org_owner, tenant_admin, and site_admin roles (hierarchy level <= 10). This prevents lower-privilege users from generating programmatic access tokens that could bypass UI-level restrictions.

Key Lifecycle

State	Description	Security Behavior
Active	Key is valid	Authenticates API requests; lastUsedAt updated on each use
Expired	Past expiration date	Automatically rejected with 401 Unauthorized
Revoked	Manually revoked by admin	Permanently rejected; revocation is irreversible
Deleted	Record removed from database	Key hash and metadata permanently purged

Authentication Flow

When an external client makes an API request:

Client → Authorization: Bearer probeya_sk_live_a1b2c3d4...
                                    ↓
Server → Extract 8-char prefix ("a1b2c3d4")
                                    ↓
Server → Query DB: WHERE prefix = "a1b2c3d4" AND organizationId = ctx.orgId
                                    ↓
Server → bcrypt.compare(fullKey, storedHash)
                                    ↓
Server → Check expiry, revocation status, and scopes
                                    ↓
Server → Execute request with the key creator's user context

Key Rotation

The Rotate action atomically revokes the current key and creates a new one in a single database transaction:

1. Click Rotate next to the key you want to rotate.
2. Copy the new key immediately.
3. Update the key in your integration or CI/CD system.
4. The old key is immediately revoked and will no longer authenticate.

Enterprise Rotation Policy

For GxP-validated environments, establish a key rotation policy in your SOP:

Risk Level	Rotation Frequency	Rationale
Critical integrations (MES, LIMS)	Every 90 days	Limits exposure window for compromised keys
Non-critical integrations (dashboards)	Every 180 days	Lower risk, reduced operational overhead
Temporary project keys	Set expiration date at creation	Automatic expiry eliminates forgotten keys
Post-incident	Immediately	Any suspected compromise requires immediate rotation

Scope Design for Integration Teams

Pattern 1: MES Integration (Read/Write KPIs + Read Items)

Name:   "MES Integration - Brussels OEE Feed"
Scopes: ["write:kpis", "read:kpis", "read:items"]
Expiry: 90 days

Pattern 2: Executive Dashboard (Read Only)

Name:   "Portfolio Dashboard - C-Suite"
Scopes: ["read:dashboard", "read:kpis", "read:items"]
Expiry: 180 days

Pattern 3: CI/CD Pipeline (Full Access)

Name:   "GitHub Actions - Deployment Pipeline"
Scopes: [] (full access)
Expiry: 30 days

warning

Full-access keys (scopes: []) should be rare and tightly controlled. Prefer scoped keys that follow the principle of least privilege. Document each full-access key's justification in your change control record.

Permissions & Security

• API key management is done via session authentication (the settings UI), not via API keys themselves. You cannot create or revoke keys using another API key -- this prevents automated privilege escalation.
• All operations are scoped to the current organization for multi-tenant isolation.
• All CRUD operations are logged to the audit trail for compliance.
• API keys cannot access features above the organization's plan level.

Troubleshooting

Symptom	Cause	Resolution
401 Unauthorized	Key is expired, revoked, or malformed	Check key status in Settings > API Keys; create a new key if needed
403 Forbidden	Key lacks the required scope, or feature is above plan level	Create a new key with broader scopes, or upgrade the plan
Key not shown after creation	Page was refreshed before copying	Create a new key (the old one's plaintext is permanently lost)
Cannot create keys	User lacks manage_settings permission	Ask an org_owner or tenant_admin to create the key
429 Too Many Requests	Rate limit exceeded	Implement exponential backoff in your integration client

Recovery Procedures

Scenario	Resolution
API key compromised	Immediately revoke the key in Settings > API Keys. Create a new key. Review the audit log for unauthorized activity.
Integration broke after key rotation	Verify the new key is correctly deployed in the integration system. Check for cached old keys in CI/CD secrets.
All API keys accidentally revoked	Create new keys. Revocation is irreversible -- there is no undo.
Key creator left the organization	The key remains valid until explicitly revoked. Audit all keys owned by departing users and revoke/rotate as needed.

Related Features

• Webhooks -- Push event notifications to external systems (complement to pull-based API access).
• Connectors -- Pre-built bidirectional sync with SAP, TrackWise, and other pharma systems.
• Integrations -- Slack and Teams notification integrations.
• Audit Log -- API key creation, usage, revocation, and deletion events are logged.
• Security Settings -- Session policies and 2FA enforcement.