Managing API Keys

Article Type: Configuration / How-To
Audience: Enterprise Administrators
Module: Access Control
Applies to Versions: All Versions
Estimated Time: 15-20 minutes

1. Overview

API Keys provide secure, programmatic access to the Fuuz platform for external system integrations. Enterprise Administrators use API Keys to enable external systems, middleware platforms, and custom applications to authenticate and interact with Fuuz GraphQL APIs, Data Flows, webhooks, and other platform resources. Each API Key is scoped to a single tenant and assigned to an API Access user with specific RBAC permissions.

Common Use Cases

• ERP Integration: External ERP systems pushing data to Fuuz via user interactions or automated processes
• Middleware & iPaaS: Integration platforms querying Fuuz data for synchronization or workflow automation
• Edge Systems: Industrial systems like Ignition pulling enterprise configuration or master data from Fuuz
• Custom Applications: Custom-built UIs, mobile apps, or frontline worker tools accessing Fuuz data and services

Key Concepts

• Tenant Scope: Each API Key is scoped to a single tenant. Multi-tenant integrations require multiple keys.
• API Access Users: API Keys are assigned to API Access type users that follow standard RBAC with Policy Groups.
• One-Time Visibility: API Keys are displayed only once at creation. If lost, a new key must be generated.
• Enterprise Admin Only: Only Enterprise Administrators can create, manage, and inactivate API Keys.

2. Prerequisites

• Access Level: Enterprise Administrator with Enterprise Admin Home access
• Permissions: Access Control management permissions
• Resources: API Access user with access to target tenant must exist

3. Procedure Steps

Step 1: Navigate to API Keys

Access the API Keys management interface to view existing keys and create new ones.

1. Navigate to Enterprise Admin → Access Control → API Keys
2. The API Keys table displays existing keys with columns: Id, Name, Active, User, Tenant, Last Authenticated At
3. Review existing keys and their authentication status

Step 2: Create New API Key

Generate a new API Key and assign it to an API Access user.

1. Click the + (Add) button in the toolbar
2. The Create a new User Api Key dialog opens
3. Complete the required fields:
   • Name (required): Unique identifier; use descriptive naming (e.g., "ERP-Production-Integration")
   • Tenant (required): Select application; filters available users to those with tenant access
   • User (required): Select API Access user from filtered list
4. Click + (Submit) to generate the key

Step 3: Secure the Generated Key

Copy and store the API Key immediately as it will never be displayed again.

1. The API Key dialog displays with the generated key
2. CRITICAL: Copy the API Key immediately
3. Click the copy button or manually select and copy the entire key string
4. Store the key in your organization's secure credential management system
5. Close the dialog only after confirming the key is securely stored

Step 4: Configure RBAC Permissions

Assign Policy Groups to control what the API Key can access.

1. Navigate to the tenant specified when creating the key
2. Go to Access Control → App Users
3. Locate the API Access user associated with the key
4. Assign appropriate Policy Groups (not Roles):
   • Grant access to specific API resources and Data Flows
   • Avoid assigning screen access
   • Use separate API-specific Policy Groups
5. Configure security policies:
   • IP restrictions if integration comes from known addresses
   • Data model field-level permissions for sensitive data
   • Read-only operations if integration only queries data

Step 5: Multi-Tenant Integration Setup (If Needed)

For external systems requiring access to multiple applications, create separate keys for each tenant.

1. Create separate API Access users for each tenant
2. Generate separate API Keys for each tenant
3. Configure RBAC independently within each application context
4. External system manages multiple keys and routes requests appropriately

4. Configuration Reference

API Key Fields

API Capabilities

Licensing Model

• Licensing Level: API Integration capability at the integration level
• Multiple Integration Points: Single API Key may support multiple integration points
• Rate Limits: No technical rate limits on API Keys
• Soft Limits: Exceeding licensed integration points triggers billing update; service not interrupted
• Key Quantity: No system limit on number of keys per user or tenant

5. Validation & Testing

Success Criteria:

• ✓ API Key created and securely stored in credential management system
• ✓ API Access user has appropriate Policy Groups assigned
• ✓ External system successfully authenticates using the key
• ✓ Integration can access required Fuuz resources (GraphQL, Data Flows, etc.)
• ✓ Last Authenticated At timestamp updates when key is used
• ✓ Authentication Events report shows successful authentications

Testing Procedure

1. Configure external system with the new API Key
2. Attempt authentication from the external system
3. Verify successful authentication in Enterprise Admin → Access Control → Authentication Events
4. Test access to specific resources (e.g., query a data model, trigger a Data Flow)
5. Verify proper authorization based on assigned Policy Groups
6. Check that Last Authenticated At timestamp updated in API Keys table

Key Management Operations

Inactivating API Keys:

1. Navigate to Enterprise Admin → Access Control → API Keys
2. Select the API Key to inactivate
3. Uncheck the Active checkbox
4. Verify integrations using the key immediately fail authentication

Reactivating API Keys:

1. Filter the API Keys table to show inactive keys
2. Select the inactive key to reactivate
3. Verify associated user, tenant, and user access are still active
4. Check the Active checkbox
5. Verify integrations can authenticate again immediately

Best Practices

• Naming Convention: Use pattern [System]-[Environment]-[Purpose] (e.g., "SAP-Production-OrderSync")
• Key Rotation: Establish key rotation schedule; currently requires creating new key and inactivating old
• Monitoring: Review Last Authenticated At column monthly to identify unused keys
• Security: Use IP restrictions for integrations from known static addresses
• RBAC: Create separate API-specific Policy Groups; avoid reusing web user policies
• Documentation: Maintain external documentation mapping keys to integration systems

6. Troubleshooting

Using Authentication Events Report

To investigate API Key authentication issues:

1. Navigate to Enterprise Admin → Access Control → Authentication Events
2. Filter by the API Access user associated with the key
3. Review failed authentication attempts for error codes
4. Common failures: Invalid credentials, IP restriction violation, User inactive, Tenant access revoked

7. Related Resources

• Managing Enterprise Users: Creating and configuring API Access type users
• Access Control Overview: Fuuz access control model including Policy Groups
• Managing App Users: Configuring RBAC at application level
• Authentication Events: Security monitoring and troubleshooting
• GraphQL API Documentation: Technical reference for Fuuz GraphQL APIs
• Data Flow Integration Guide: Triggering and monitoring Data Flows via API

8. Revision History