Authentication
===============

To ensure secure access to the API, we support two authentication methods: **JWT-based authentication** and **API key-based authentication**. Both methods are designed to provide flexibility and security, allowing you to choose the approach that best fits your use case.

----

JWT-Based Authentication
-------------------------

JWT (JSON Web Token) authentication is a token-based method that requires users to log in and obtain a token for subsequent API requests. This method is ideal for scenarios where user-specific access control is required.

**How It Works:**

1. **Login Request**: Send a ``POST`` request to the ``/api/Account/login`` endpoint with your credentials (e.g., email and password).
2. **Receive Token**: Upon successful authentication, the server responds with a JWT token.
3. **Use the Token**: Include the token in the ``Authorization`` header of your API requests as a Bearer token.

**Example:**

.. code-block:: http

    POST /api/Account/login HTTP/1.1
    Host: api.quantamatics.com
    Content-Type: application/json

    {
      "email": "your_email",
      "password": "your_password"
    }

**Response:**

.. code-block:: json

    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "user": {
         "id": 000,
         ...
      }
    }

**Using the Token in Requests:**

.. code-block:: http

    GET api/data/endpoint HTTP/1.1
    Host: api.quantamatics.com
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The token is valid for a specific duration (e.g., 24 hours). After expiration, you will need to log in again to obtain a new token.

----

API Key-Based Authentication
-----------------------------

For simpler use cases or server-to-server communication, you can use a static API key. This method is straightforward and does not require user login.

**How It Works:**

1. **Obtain an API Key**: Contact support to request your unique API key.
2. **Use the API Key**: Include the API key in the ``X-API-Key`` header of your API requests.

**Example:**

.. code-block:: http

    GET api/data/endpoint HTTP/1.1
    Host: api.quantamatics.com
    X-Api-Key: your_api_key_here

API keys are static and do not expire unless explicitly revoked. Ensure you store your API key securely and avoid exposing it in client-side code or public repositories.

----

Best Practices for Authentication
---------------------------------

- **Use HTTPS**: Always make API requests over HTTPS to encrypt data in transit and prevent interception. *The API will reject insecure calls.*
- **Secure Storage**: Store your JWT tokens and API keys securely, such as in environment variables or secure credential storage systems.
- **Token Expiry**: Regularly refresh JWT tokens to minimize the risk of unauthorized access.
- **Key Rotation**: Periodically rotate API keys and revoke unused keys to enhance security.