Authentication & Access Control

FoxNose separates how you manage content (Management API) from how you deliver it (Flux API). Each layer has its own authentication model and permissions so you can give every user, script, or partner the minimum access they need.

---

Authentication Fundamentals

There are two authentication mechanisms in FoxNose:

• User authentication (JWT) – Humans sign in to the dashboard or run scripts on their behalf. After entering email/password, you receive {access, refresh} tokens and send requests with Authorization: Bearer <access_token>. This applies only to the Management API.
• Service authentication (API keys) – Applications, servers, or automation jobs call APIs with long-lived credentials. API keys are created in the dashboard and scoped either to the Management API or Flux API.

---

Securing the Management API

The Management API powers everything you do in the dashboard—creating folders, publishing content, configuring Flux, managing access. Control is granted through roles assigned either to human users (JWT) or to API keys (service accounts).

Management API Key Roles

Role	Scope	Typical Use
Organization Owner / Administrator	Entire organization (projects, billing, users)	Company-wide administrators
Project Administrator	A single project and its environments	Product or team-level owners
Granular Role	Specific environment	Custom set of permissions for targeted tasks (CI/CD, import scripts, partner access)

Granular roles let you pick exactly which entities and actions are allowed (e.g., “Create resources but cannot delete environments”). They are recommended for automation and API keys.

Permission Categories

When you create a granular role, you configure permissions across four categories:

Content Management — Work with folders, resources, and data structures

Permission	Description	Actions
Folder Contents	View the list of resources and subfolders without accessing their contents. Enable "All Folders" to grant access to all folders automatically.	Read
Folders	View and manage the organization and hierarchy of folders.	Create, Read, Update, Delete
Resources	Create, view, and manage resources within folders, including opening and editing their contents.	Create, Read, Update, Delete
Schemas	Create and manage schemas for collection folders.	Create, Read, Update, Delete

Environment Management — Manage environment settings and configurations

Permission	Description	Actions
Environment Settings	View and modify environment configurations, including enabling or disabling environments. Does not permit environment deletion.	Read, Update

Management API — Manage API keys and roles for administrative operations

Permission	Description	Actions
Management API Roles	Create, view, and manage roles for accessing the system via the UI or Management API keys.	Create, Read, Update, Delete
Management API Keys	Create, view, and manage API keys for accessing the Management API.	Create, Read, Update, Delete

Flux API — Manage content delivery API keys, roles, and endpoints

Permission	Description	Actions
Flux APIs	Create and manage Flux APIs and their folder connections.	Create, Read, Update, Delete
Flux API Roles	Manage access to the Flux API through role assignments.	Create, Read, Update, Delete
Flux API Keys	Create, view, and manage API keys for accessing the Flux API.	Create, Read, Update, Delete

Best Practices

1. Use least privilege – Create dedicated roles (and keys) per environment and integration. Avoid sharing owner-level accounts with automation scripts.
2. Rotate secrets regularly – Re-issue API keys and update the consuming services. Disable old keys immediately.
3. Audit folder connections – Periodically review which folders are connected to each Flux API and whether both get_one and get_many are required.
4. Secure production Flux APIs – Leave prototypes public, but switch production APIs to “Require API key authentication” and use Secure mode signatures.
5. Log access – Both Management and Flux APIs return structured error codes; log them along with the error_code to detect unauthorized attempts.

---

Access Audit

FoxNose automatically records an audit trail of all content changes across your organization. Every create, update, or delete action generates an immutable event record. Events are retained for 30 days.

There are two levels of audit logs:

• Organization events — Track changes to organization-wide entities: users, projects, and environment lifecycle. Available in the Activity Log section of your organization dashboard.
• Environment events — Track changes within a specific environment: folders, resources, schemas, API keys, roles, and more. Available in the Activity Log section of each environment.

What Gets Logged

Events capture who changed what and when:

• Actor — The user or API key that performed the action
• Action — Create, update, or delete
• Entity — The affected item (folder, resource, API key, role, etc.)
• Timestamp — When the change occurred
• Context — IP address and request origin (hostname only)

For destructive actions, a snapshot of the entity's last state is preserved, so you can see what was deleted.

What Stays Private

Audit logs focus on metadata, not content. Request bodies, response payloads, and sensitive headers are never stored. This keeps logs lightweight and avoids exposing confidential data in audit reports.

Filtering and Access

The Events API provides rich filtering by entity type, actor, time range, IP address, and more. Results are automatically scoped to what the caller can see:

• Admins (organization, project, or users with full environment access) see all events
• Granular roles see only events for entities their permissions allow them to read—including object-level folder restrictions

This means you can safely grant Events API access to automation or partners without worrying about leaking audit data for resources they cannot access.

---

Related Guides

• Management API Authentication → JWT flows, Secure vs Simple headers, API key management.
• Flux API Authentication → Simple vs Secure mode, signature payloads, header examples.
• Manage Roles and Manage Keys → Provision and assign roles/keys inside environments.
• Flux Roles & Keys and Flux API Keys → Control delivery-level access.
• Events API → Query audit logs, filter by entity, actor, or time range.