# API Key Management

### 3.1. Assign API Key

* **URL**: `/assign-api-key`
* **Method**: `POST`
* **Description**: Assigns a new API key to a user. **Admin only**.
* **Authentication**: HTTP Basic (Admin credentials)
* **Request Body**:
  * **Content-Type**: `application/json`
  * **Schema**: `AssignAPIKeyRequest`

    ```json
    {
      "username": "string (3-50 characters, alphanumeric)"
    }
    ```
* **Responses**:
  * **200 OK**

    ```json
    {
      "message": "API key generated successfully.",
      "api_key": "op-<user_hash>-<key_hash>"
    }
    ```
  * **400 Bad Request**

    * **Reason**: User already has a valid API key or validation error.

    ```json
    {
      "detail": "User already has a valid API key."
    }
    ```
  * **404 Not Found**

    * **Reason**: User does not exist.

    ```json
    {
      "detail": "User not found."
    }
    ```
  * **500 Internal Server Error**

    ```json
    {
      "detail": "Failed to store API key."
    }
    ```
  * **401 Unauthorized**

    ```json
    {
      "detail": "Unauthorized"
    }
    ```

### 3.2. Generate API Key

* **URL**: `/generate-api-key`
* **Method**: `POST`
* **Description**: Generates a new API key for the authenticated user. If the user already has a valid API key, it returns the existing key.
* **Authentication**: HTTP Bearer (User API Key)
* **Parameters**: None
* **Responses**:
  * **200 OK**

    ```json
    {
      "message": "API key generated successfully.",
      "api_key": "op-<user_hash>-<key_hash>"
    }
    ```

    * **Or**, if an API key already exists:

    ```json
    {
      "message": "API key already exists.",
      "api_key": "op-<user_hash>-<key_hash>"
    }
    ```
  * **500 Internal Server Error**

    ```json
    {
      "detail": "Failed to store API key."
    }
    ```
  * **401 Unauthorized**

    ```json
    {
      "detail": "Invalid or expired API key."
    }
    ```

### **3.3. Validate API Key**

* **URL**: `/validate-api-key`
* **Method**: `GET`
* **Description**: Validates whether a given API key is valid and active.
* **Authentication**: None
* **Query Parameters**:
  * `api_key` (string, required): The API key to validate.
* **Responses**:
  * **200 OK**

    ```json
    {
      "message": "API key is valid",
      "username": "string"
    }
    ```
  * **401 Unauthorized**

    ```json
    {
      "detail": "Invalid or expired API key"
    }
    ```

### 3.4. Revoke API Key

* **URL**: `/revoke-api-key`
* **Method**: `POST`
* **Description**: Revokes an API key. Admins can revoke any API key by providing it in the request body. Regular users can revoke their own API key.
* **Authentication**: HTTP Bearer (Admin API Key or User API Key)
* **Request Body**:
  * **For Admins**:
    * **Content-Type**: `application/json`
    * **Schema**:

      ```json
      {
        "api_key": "string"
      }
      ```
  * **For Users**:
    * **Body**: `None` (Revokes their own API key)
* **Responses**:
  * **200 OK**
    * **Admin**:

      ```json
      {
        "message": "API key 'op-<user_hash>-<key_hash>' has been revoked."
      }
      ```
    * **User**:

      ```json
      {
        "message": "Your API key has been revoked."
      }
      ```
  * **400 Bad Request**

    * **Reason**: Missing API key in the request body (for admins).

    ```json
    {
      "detail": "API key must be provided for revocation (admin)."
    }
    ```
  * **404 Not Found**

    * **Reason**: API key not found or already revoked.

    ```json
    {
      "detail": "API key not found or already revoked."
    }
    ```
  * **401 Unauthorized**

    ```json
    {
      "detail": "Invalid or expired API key."
    }
    ```

***
