# How Fluxer Handles the .well-known/fluxer Discovery Document for Instance Validation

> Fluxer uses its /.well-known/fluxer discovery document for automated client validation. Learn how this JSON document reveals API endpoints federation status and public keys.

- Repository: [Fluxer/fluxer](https://github.com/fluxerapp/fluxer)
- Tags: deep-dive
- Published: 2026-03-17

---

**Fluxer publishes a canonical `/.well-known/fluxer` endpoint on every instance that returns a JSON discovery document containing API endpoints, federation status, and public keys, enabling automated validation by clients and federated services.**

Fluxer implements a standards-based instance discovery mechanism through the `.well-known/fluxer` endpoint that every instance must publish. This discovery document serves as the authoritative source for API locations, feature flags, and cryptographic credentials required for secure federation. According to the fluxerapp/fluxer source code, the implementation spans both the TypeScript API service and the Erlang relay system to ensure reliable validation across the network.

## Endpoint Implementation and Middleware

The discovery endpoint is defined in [`packages/api/src/instance/InstanceController.tsx`](https://github.com/fluxerapp/fluxer/blob/main/packages/api/src/instance/InstanceController.tsx). According to lines 35-48 of the source, the controller registers the route at `/.well-known/fluxer` using a standard HTTP GET handler and applies `RateLimitMiddleware` to prevent abuse.

The response schema is enforced with `WellKnownFluxerResponse`, ensuring type safety and consistent JSON structure. The implementation automatically sets the `Access-Control-Allow-Origin: *` header to enable cross-origin requests from web-based clients and federated instances.

The route is wired into the Hono server in [`fluxer_server/src/Routes.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_server/src/Routes.tsx) at line 130, making the endpoint available immediately upon server startup without additional configuration.

## Discovery Document Structure

The JSON response aggregates configuration from the global `Config` object and runtime instance settings. The document contains several critical sections:

- **API Versioning**: The `api_code_version` field indicates the server software version
- **Endpoint URLs**: Absolute URLs for the client API, gateway, media server, and public endpoints
- **Feature Flags**: Captcha configuration, SMS MFA availability, and other capability toggles
- **Operational Limits**: Rate limiting thresholds and quota information
- **Federation Metadata**: When enabled, includes the instance's public key and OAuth 2.0 discovery endpoints

The `public_key` object uses the X25519 algorithm for federation identity verification, containing `id`, `algorithm`, and `public_key_base64` fields. The `oauth2` section provides the authorization and token endpoints required for federated authentication flows.

## Instance Validation and Caching

The Erlang relay system consumes this document to validate and locate Fluxer instances. In [`fluxer_relay/src/relay/fluxer_relay_instance_discovery.erl`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_relay/src/relay/fluxer_relay_instance_discovery.erl) (lines 62-75 and 120-144), the `discover_gateway/1` function implements a robust caching mechanism to minimize network overhead.

The validation process follows these steps:

1. Check the ETS cache for existing gateway information for the target domain
2. On cache miss, perform an HTTP GET to `https://{instanceDomain}/.well-known/fluxer`
3. Parse the JSON response and extract the `gateway` endpoint URL
4. Cache the parsed result for five minutes before allowing expiration

If the HTTP request fails, returns invalid JSON, or lacks a valid gateway URL, the relay returns an error tuple, preventing connection to misconfigured or non-existent instances.

## Working with the Discovery Document

### Fetching the Document via HTTP

Clients can retrieve the discovery document using standard HTTP requests:

```bash
curl -s https://myinstance.example.com/.well-known/fluxer | jq .

```

A typical response includes:

```json
{
  "api_code_version": "2026.0.0",
  "endpoints": {
    "api": "https://api.myinstance.example.com",
    "gateway": "https://gateway.myinstance.example.com",
    "media": "https://media.myinstance.example.com"
  },
  "features": {
    "sms_mfa_enabled": true
  },
  "federation": {
    "enabled": true,
    "version": "1"
  },
  "public_key": {
    "id": "https://myinstance.example.com/.well-known/fluxer#main-key",
    "algorithm": "x25519",
    "public_key_base64": "ABCD..."
  }
}

```

### Validating Instances in Erlang

Services can validate and locate gateways programmatically:

```erlang
{ok, GatewayInfo} = fluxer_relay_instance_discovery:discover_gateway("myinstance.example.com").

```

The `GatewayInfo` map contains `host`, `port`, and `use_tls` fields extracted from the discovery document's gateway endpoint.

### Extending Discovery with Custom Features

To expose new capabilities to clients, modify [`packages/api/src/Config.tsx`](https://github.com/fluxerapp/fluxer/blob/main/packages/api/src/Config.tsx):

```typescript
export const Config = {
  features: {
    new_feature_enabled: true,
    // Existing flags...
  },
};

```

The `InstanceController` automatically includes `Config.features` in the discovery response, making the new flag visible to all clients without requiring changes to the route handler.

## Summary

- The `/.well-known/fluxer` endpoint is implemented in [`packages/api/src/instance/InstanceController.tsx`](https://github.com/fluxerapp/fluxer/blob/main/packages/api/src/instance/InstanceController.tsx) with rate limiting via `RateLimitMiddleware` and CORS headers for cross-origin access
- The discovery document contains API versioning, endpoint URLs, feature flags, rate limits, and federation credentials including X25519 public keys
- The Erlang relay in [`fluxer_relay_instance_discovery.erl`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_relay_instance_discovery.erl) caches discovery results for five minutes in ETS to optimize validation performance
- Configuration changes propagate automatically through the global `Config` object, requiring no code changes to update the discovery document

## Frequently Asked Questions

### What information does the .well-known/fluxer discovery document contain?

The document returns a JSON object containing the `api_code_version`, endpoint URLs for API, gateway, and media services, feature flags such as `sms_mfa_enabled`, operational limits, and federation metadata. When federation is enabled, it also includes the instance's public key and OAuth 2.0 endpoint URLs required for secure inter-instance communication.

### How does Fluxer prevent abuse of the discovery endpoint?

The `InstanceController` applies `RateLimitMiddleware` to the `/.well-known/fluxer` route to limit request frequency. This prevents denial-of-service attacks against the discovery mechanism while still allowing legitimate clients and federated instances to perform validation.

### How long does the relay cache discovery document results?

The Erlang relay implementation caches successful discovery results for five minutes in an ETS table. This reduces redundant HTTP requests to target instances while ensuring that gateway information remains reasonably fresh for routing decisions.

### Can I customize the discovery document for my Fluxer instance?

Yes. By modifying the `Config` object in [`packages/api/src/Config.tsx`](https://github.com/fluxerapp/fluxer/blob/main/packages/api/src/Config.tsx), you can add custom feature flags or adjust endpoint URLs. The `InstanceController` automatically incorporates these changes into the discovery document response without requiring modifications to the route handler or response schema.