Add API authentication guide for third-party integrators

[Mystery-CLI]

Background

FuTuRe exposes a REST API that third-party developers and integration partners use to build on top of the platform's Stellar-based payment infrastructure. Currently, there is no dedicated documentation explaining how to obtain API credentials, authenticate requests, refresh tokens, or handle authentication errors. Integration partners must ask the core team directly for guidance, and internal developers onboarding to the API must read through the route middleware source code to understand the authentication model. This is a significant friction point for ecosystem growth.

Problem

The absence of an API authentication guide creates concrete problems for every category of API consumer:

• Third-party integrators have no starting point. Partners who want to integrate FuTuRe's payment API into their products cannot proceed without reaching out to the team for basic credential and authentication information that should be self-service.
• Token management is opaque. The lifetime of access tokens, the mechanism for refreshing them, and what to do when a token expires are not documented anywhere accessible.
• Error responses are undocumented. When authentication fails, the API returns error codes and messages whose meaning and remediation steps are not explained, leading to integrators contacting support for issues they could resolve themselves.
• Security misuse risk. Without guidance, some integrators may store tokens insecurely, use them across environments, or fail to implement token rotation — creating security risks for their users and for the platform.
• Example requests are absent. Developers learn most effectively from working examples. Without curl or code snippets showing authentication in practice, adoption is slower than it needs to be.

Proposed Solution

Create docs/api-auth.md with comprehensive documentation covering the full authentication lifecycle. The document should include:

1. Overview of the authentication model — whether the API uses JWT bearer tokens, API keys, or OAuth 2.0, and a brief description of the flow.
2. Obtaining credentials — how to create an API application, generate a client ID and secret, and where credentials appear in the dashboard.
3. Authenticating requests — the exact request format for obtaining an access token, with a working curl example.
4. Using the access token — how to attach the token to API requests using the Authorization header, with examples across common HTTP libraries (curl, fetch, axios).
5. Token lifetime and refresh — the token expiry duration, how to detect expiry, and how to refresh without requiring the user to re-authenticate.
6. Scopes and permissions — if the API uses scopes, an explanation of what each scope grants access to and how to request them.
7. Error reference — a table of authentication-related error codes with their meanings and remediation guidance.
8. Security best practices — guidance on storing credentials, using separate keys per environment, rotating secrets, and avoiding common mistakes.

Implementation Steps

1. Audit the authentication middleware in backend/src/auth/ and backend/src/routes/auth.js to accurately document the current implementation.
2. Draft docs/api-auth.md covering all sections listed above.
3. Write and verify all curl example requests against a local running instance of the API.
4. Have the document reviewed by a developer who has not previously worked on the auth system to validate clarity.
5. Link docs/api-auth.md from the main docs/README.md and from relevant README sections.

Acceptance Criteria

• docs/api-auth.md exists and covers all sections outlined in this issue.
• All curl examples in the document are verified to work against the current API.
• The document explains token lifetime, the refresh flow, and error codes.
• The document is linked from the main documentation index.

Notes

The guide should use placeholder values for credentials and sensitive data rather than real examples. Indicate clearly which base URL to use for production vs sandbox environments. If OAuth 2.0 flows are supported in future, this document should be the natural place to extend.