Backend MVP stabilization: Arc76 auth, subscription enforcement, and network metadata reliability

[ludovit-scholtz]

Summary

Stabilize the backend API to support the MVP subscription business model and SaaS-style authentication by ensuring reliable API connectivity, subscription enforcement, and consistent network metadata delivery. This issue focuses on making the backend dependable for production workloads and for the frontend SaaS experience: Arc76 email/password authentication workflows must be supported, Arc14 secure backend communication must be enforced, subscription status must be checked on relevant API endpoints, and a unified network metadata response should be delivered for production networks and testnets. The goal is to remove backend instability as an MVP blocker and create a trustworthy foundation for the paid platform.

Business Value

Revenue cannot be generated without a functioning backend that enforces subscription plans and guarantees consistent API behavior. The roadmap makes it clear that the subscription system is not operational, which means the business cannot sell its core product. Reliable subscription enforcement and authentication are the gatekeepers for all premium functionality. If the backend returns inconsistent results or fails to validate subscription status, customers will lose trust, and the enterprise market will view the platform as non-compliant.

In regulated asset issuance, trust and auditability are critical. Customers will not deploy regulated tokens if the platform cannot reliably confirm who is authenticated, whether the user has access, and which network is being used for deployment. A stable backend provides the data integrity necessary for compliance. It also reduces support costs and engineering time spent on firefighting outages or inconsistent behavior, freeing the team to move toward enterprise compliance milestones.

Additionally, when network metadata is consistent and documented, the frontend can confidently prioritize mainnet networks without guesswork. This reduces the time to market for production deployments and helps the product leadership communicate a clear “production ready” message to customers. Backend stability therefore directly improves conversion, retention, and the ability to deliver on the revenue targets.

Product overview

See the product vision and roadmap for context: https://raw.githubusercontent.com/scholtz/biatec-tokens/refs/heads/main/business-owner-roadmap.md

Scope

In scope

1. Authentication and Arc76/Arc14 support

   • Ensure Arc76 email/password authentication is fully supported in API flows and creates self-custody accounts reliably.
   • Ensure Arc14 secure backend communication is enforced, including validation of authentication payloads and consistent error responses for invalid or expired sessions.

2. Subscription enforcement and authorization

   • Implement subscription tier validation for token creation, deployment, and any premium API endpoints.
   • Ensure the backend checks subscription state before executing high-cost or compliance-sensitive actions.
   • Provide clear error responses and error codes for subscription failures so the frontend can present appropriate UX messaging.

3. API reliability and health monitoring

   • Introduce explicit health checks for critical dependencies and respond with a clear error structure when unavailable.
   • Improve error handling so that API responses are consistent and predictable under failure scenarios.
   • Add telemetry or logging that highlights failed authentication, subscription, and deployment attempts.

4. Network metadata consistency

   • Ensure the network metadata endpoint returns prioritized mainnet networks and consistent identifiers for Algorand and EVM chains.
   • Validate that the recommended networks list aligns with the product vision and frontend UX expectations.

5. Integration readiness

   • Ensure that frontend integration can rely on consistent DTOs and response payloads for authentication, subscription, and network metadata.
   • Provide clear API documentation for the updated endpoints.

Out of scope

• Frontend UI changes and wording updates (handled in frontend issue).
• New blockchain protocol integrations beyond the current set.
• Advanced enterprise compliance tooling (phase 2 and beyond).

Technical approach and dependencies

• Build on existing authentication services rather than replacing them, ensuring minimal disruption to current flows.
• Coordinate with subscription system implementation to validate billing state in the API.
• Use existing configuration patterns to define network metadata, ensuring mainnet networks are clearly labeled.
• Ensure that any new middleware or guards are properly unit tested and integrated into the API pipeline.

Acceptance Criteria

1. Arc76 and Arc14 authentication

   • Email/password authentication is supported end-to-end and results in valid sessions.
   • Arc14 communication is enforced; invalid authentication attempts return a standard error payload.

2. Subscription enforcement

   • Premium endpoints reject requests from users without an active subscription with a clear error code.
   • Subscription validation is logged for auditability.

3. API stability and monitoring

   • API endpoints return structured error responses on failures and do not expose raw exceptions.
   • Health checks expose dependency status for integration monitoring.

4. Network metadata reliability

   • Network metadata endpoint returns a consistent list of networks with mainnets marked as recommended.
   • The identifiers returned match the frontend network selection requirements.

5. Documentation and integration readiness

   • Documentation is updated to reflect authentication, subscription, and network metadata behaviors.
   • Integration tests confirm the API behavior for each key flow.

Testing

Unit tests

• Add unit tests for authentication services validating Arc76 email/password handling and Arc14 signature validation.
• Add unit tests for subscription enforcement middleware or services, covering active, canceled, trial, and expired subscription states.
• Add unit tests for network metadata builders, verifying recommended mainnet and testnet labeling.

Integration tests

• Add integration tests that create a user account via Arc76, authenticate, and validate that protected endpoints allow access.
• Add integration tests that verify subscription-required endpoints reject requests when subscription is inactive.
• Add integration tests for network metadata endpoint, validating stable output and recommended networks list.

E2E tests

• Ensure automated API E2E tests cover sign-in, subscription validation, and token deployment readiness flows.
• Validate that errors are returned in a structured JSON format and can be parsed by the frontend.

Manual testing

• Test a full flow using a staging environment: create account, sign in, verify subscription status, call network metadata, and attempt a token deployment.
• Confirm that logging and monitoring show key events for authentication and subscription enforcement.

Documentation checks

• Update API documentation in the repository to reflect new or updated endpoints, including sample payloads and error responses.

This issue must result in a backend that is stable enough to support production traffic, enforce subscription revenue, and provide consistent data for the frontend SaaS experience. Success will be measured by a reduction in integration failures, fewer authentication-related support tickets, and the ability to deliver a reliable MVP to early enterprise customers.