API Keys

Managing API Keys

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

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.

1. Overview

Each API Key is scoped to a single tenant and assigned to an API Access user with specific RBAC permissions.

Note: Before you begin, create an API Access user via the Enterprise Users interface. The user must have access to the target tenant. See Enterprise-Users for detailed instructions on creating API Access type users.

Note: The current interface labels this feature as "User API Keys." This will be updated to "API Keys" in 2026.

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

Important: The key is displayed only once at creation. If you lose the key, you cannot retrieve it and must generate a new key. Store keys securely using your organization's credential management practices.

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

Field	Description	Notes
Id	System-generated unique identifier	Read-only; used internally
Name	Human-readable identifier	Must be unique
Active	Current status of the key	Unchecked = immediate auth failure
User	API Access user the key authenticates as	User's RBAC controls access
Tenant	Application the key provides access to	Cannot change after creation
Last Authenticated At	Timestamp of most recent use	Updates every time key is used

API Capabilities

Resource Type	Access Provided
GraphQL APIs	Query and mutate Fuuz data models
Data Flows	Trigger and monitor integration workflows
Webhooks	Receive event notifications from Fuuz
REST Endpoints	Access specialized platform services

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

Note: The Delete button in the API Keys toolbar is always disabled. API Keys cannot be deleted, only inactivated. This maintains audit history.

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

Problem	Cause	Solution
Cannot create API Key - no users in dropdown	No API Access users have access to selected tenant	Create API Access user via Enterprise Users; grant access to target tenant
Integration authentication failing	API Key inactivated or user disabled	Check key Active status and user status; reactivate if needed
Lost API Key after creation	Key not copied before closing dialog	Cannot retrieve; inactivate old key and generate new one
API calls return authorization errors	User lacks required RBAC permissions	Navigate to tenant's App Users; assign Policy Groups
Cannot reactivate API Key	User, tenant, or access no longer exists	Verify user status and access; restore or create new key
Multiple integrations stopped working	API Access user inactivated	Reactivate user in Enterprise Users interface
IP restriction blocking requests	External system IP changed	Update IP restrictions in user's Access Control Policy
Last Authenticated At not updating	Integration not authenticating successfully	Check Authentication Events report for failed attempts

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. Revision History

Version	Date	Editor	Description
1.0	2025-12-29	Fuuz Documentation Team	Initial Release

See Also

• Enterprise-Users
• Access-Types
• Authentication-Events
• Enterprise-Admin-Overview
• Make-GraphQL-Based-Calls-With-A-Token

---

Source: support.fuuz.com