Hubfly space Identity Access

Hubfly space Identity Access protects public HTTP routes before requests reach your upstream container or load balancer. It is configured per route from the Dashboard's firewall and identity controls, then enforced by Hubfly space's edge proxy on every request.

Public-route protection

Identity policies apply to managed public HTTP routes: container endpoints, custom domains, load balancer domains, and load balancer custom domains. Private project networking and HubTunnels use their own access model.

How Requests Are Evaluated

When a protected domain receives traffic, Hubfly space evaluates firewall rules first, then the identity policy, then normal routing, cache, rate-limit, and upstream proxy behavior.

1. Route policy lookup

The Dashboard stores one identity policy per route. The policy contains the route hostname, access mode, login audience, API-key settings, bypass paths, and whether identity headers should be injected upstream.

2. Proxy synchronization

Saving a policy, creating an API key, revoking a key, or changing a route domain updates the live proxy configuration for that specific container endpoint, custom domain, or load balancer route.

3. Runtime enforcement

The proxy enforces browser login grants, API-key hashes, key expiration, route-scoped allowed paths, and bypass paths before forwarding the request to your service.

Access Modes

Mode	Behavior	Best Fit
`off`	No identity authentication is enforced on the route.	Fully public websites and unauthenticated webhooks.
`login`	Browser users must sign in with a Hubfly space account that matches the route's allowed audience.	Internal dashboards, admin tools, preview apps, and private APIs used by people.
`api_key`	Every request must include a valid route access key in the configured header.	Service integrations, cron jobs, CI systems, mobile backends, and machine clients.
`login_or_api_key`	A request may pass with either a valid browser login grant or a valid API key.	Routes shared by an internal UI and automation clients.

Browser Login Flow

Login mode uses the user's Hubfly space Dashboard session to issue a short-lived route grant. If the browser has no valid route cookie, the proxy redirects the user to /access/authorize on the Hubfly space API service with the requested host, policy ID, and return path.

The proxy sees a protected browser request without a valid __Host-hf_access cookie.
The proxy redirects to the Dashboard authorize endpoint.
The authorize endpoint verifies the policy is still enabled for that host.
The signed-in user must match at least one allowed audience rule.
Hubfly space signs an access grant and redirects back to /.hubfly/access/callback on the protected domain.
The proxy validates the grant, sets the route cookie, and redirects the browser to the original path.

Login Audience Rules

A login policy can allow project readers, specific user IDs, specific email addresses, or organization roles. Project-reader access is enabled by default; if it is disabled, add at least one explicit user, email, or organization role before enabling login-only protection.

Audience Rule	What It Checks
Project readers	The signed-in user has `project:read` on the project that owns the route.
Allowed users	The user's Hubfly space user ID is present in the policy allowlist.
Allowed emails	The signed-in user's email address matches an allowlisted address.
Organization roles	The user's organization role matches one of the policy's selected roles.

API Keys

API keys are created under a route policy and are only available when the policy mode accepts keys. The default request header is X-Hubfly-Access-Key, but each policy can use another validated header name.

// Request with the default route access header

curl https://api.example.com/private \

-H "X-Hubfly-Access-Key: hfa_..."

API keys are shown once at creation time.
Hubfly space stores and syncs only the key prefix and SHA-256 hash.
Revoked keys are removed from the active proxy policy after the revoke action syncs.
Expired keys are rejected by the proxy at request time.
Allowed paths can restrict a key to one or more exact path prefixes.

Path scope behavior

API-key allowed paths are segment-aware: /admin allows /admin and /admin/users, but not /administer. Policy bypass paths are proxy-level path prefixes, so keep them narrow and explicit.

Bypass Paths

Bypass paths let selected request paths skip identity checks while the rest of the route remains protected. Use them for health probes, public assets, or callback endpoints that must stay reachable without a user session or API key.

Path	Typical Use
`/health`	Allow uptime and load-balancer probes to pass without credentials.
`/public`	Expose static or marketing assets while keeping application routes private.
`/webhooks/provider`	Leave a provider callback public while validating provider signatures in your app.

Identity Headers To Upstream

When header injection is enabled, the proxy passes verified identity context to your upstream service. API-key credentials are removed from the forwarded request before the upstream receives it.

Header	Set When
`X-Hubfly-Access-Type`	Any identity check passes. Values are `user` or `api_key`.
`X-Hubfly-Access-Policy-Id`	The request matched a configured route identity policy.
`X-Hubfly-User-Id`	A browser login grant passed.
`X-Hubfly-User-Email`	A browser login grant passed and includes the user's email.
`X-Hubfly-Access-Key-Id`	An API key passed.

Audit And Troubleshooting

Proxy request logs include identity fields so you can filter by access outcome, policy, API key, subject, or reason. Common reasons include missing API keys, invalid grants, expired keys, path denials, login redirects, and bypassed paths.

Symptom	Likely Cause	Fix
Browser redirects to login	No valid Hubfly space session or no valid route cookie.	Sign in, then retry the original protected URL.
Signed-in user sees access blocked	The user is not a project member and is not in the route allowlist.	Add the user, email, or organization role, or enable project-reader access.
API request returns `401`	Missing, invalid, expired, revoked, or path-scoped API key.	Check the header name, key status, expiration, and allowed paths.
Policy change does not affect traffic	The proxy route configuration did not sync or the wrong route was edited.	Verify the selected hostname and route type, then save the policy again.

Related API Endpoints

The Dashboard uses the project networking access endpoints to list protected routes, read a policy, update policy settings, create API keys, and revoke API keys.

GET /api/v1/projects/:projectId/network/access/routes
GET /api/v1/projects/:projectId/network/access
PUT /api/v1/projects/:projectId/network/access/update
POST /api/v1/projects/:projectId/network/access/keys/create
POST /api/v1/projects/:projectId/network/access/keys/revoke