Introduce User API Key Admin Endpoints and Model Configuration SDK API #4

hetavi-bluexkye · 2025-12-10T12:27:52Z

Summary

This PR adds user API key management endpoints to the RAGFlow admin interface, allowing administrators to generate and retrieve API keys for users. It also includes SDK API endpoints for model management, enabling users to add, remove, list, and configure default models. Additionally, it includes comprehensive test infrastructure improvements with proper cleanup mechanisms for API tokens and related cache data.

Changes

Features

Admin API Endpoints

User API Key Generation Endpoint: Added POST /admin/users/<user_name>/api_key endpoint to generate new API keys for users
User API Key Retrieval Endpoint: Added GET /admin/users/<username>/api_key endpoint to retrieve all API keys for a user
Both endpoints require admin authentication and authorization

SDK API Endpoints (Model Management)

Add Model Endpoint: Added POST /api/v1/models endpoint to add models for a user by factory and API key
Remove Model Endpoint: Added DELETE /api/v1/models endpoint to remove all models for a factory
List User Models Endpoint: Added GET /api/v1/models endpoint to list all configured models for a user
Set Default Models Endpoint: Added POST /api/v1/models/default endpoint to set default models (chat, embedding, ASR, image-to-text, rerank, TTS)
Get Default Models Endpoint: Added GET /api/v1/models/default endpoint to retrieve default model configurations
All SDK endpoints require API token authentication

API Endpoints

Admin API Endpoints

Generate User API Key

POST /api/v1/admin/users/<user_name>/api_key

Response:

{
  "code": 0,
  "data": {
    "token": "ragflow-...",
    "beta": "...",
    "tenant_id": "...",
    "create_date": "...",
    "update_date": null
  },
  "message": "API key generated successfully"
}

Get User API Keys

GET /api/v1/admin/users/<username>/api_key

Response:

{
  "code": 0,
  "data": [
    {
      "token": "ragflow-...",
      "beta": "...",
      "tenant_id": "...",
      "dialog_id": "...",
      "source": "...",
      "create_date": "...",
      "update_date": "..."
    }
  ],
  "message": "Get user API keys"
}

SDK API Endpoints

Add Model

POST /api/v1/models

Request Body:

{
  "llm_factory": "OpenAI",
  "api_key": "sk-...",
  "base_url": "https://api.openai.com/v1"  // optional
}

Response:

{
  "code": 0,
  "data": true,
  "message": "Success"
}

Notes:

Validates API key by testing access to at least one model of each type (chat, embedding, rerank)
Supports special factory authentication methods (VolcEngine, Tencent, Bedrock, BaiduYiyan, Fish Audio, Google Cloud, Azure-OpenAI, OpenRouter)
Self-deployed models (LocalAI, Ollama, Xinference, etc.) skip API key validation

Remove Model

DELETE /api/v1/models

Request Body:

{
  "llm_factory": "OpenAI"
}

Response:

{
  "code": 0,
  "data": true,
  "message": "Success"
}

List User Models

GET /api/v1/models?include_details=false

Query Parameters:

include_details (bool, optional): Whether to include detailed information (api_base, max_tokens, status). Default: false

Response:

{
  "code": 0,
  "data": {
    "OpenAI": {
      "tags": {...},
      "llm": [
        {
          "type": "chat",
          "name": "gpt-4",
          "used_token": 0,
          "api_base": "...",  // if include_details=true
          "max_tokens": 8192,  // if include_details=true
          "status": "1"  // if include_details=true
        }
      ]
    }
  },
  "message": "Success"
}

Set Default Models

POST /api/v1/models/default

Request Body:

{
  "llm_id": "gpt-4",
  "embd_id": "text-embedding-ada-002",
  "asr_id": "whisper-1",
  "img2txt_id": "gpt-4-vision-preview",
  "rerank_id": "bge-reranker-base",
  "tts_id": "tts-1"
}

Response:

{
  "code": 0,
  "data": true,
  "message": "Success"
}

Notes:

All fields are optional, but at least one must be provided
Validates that all provided model IDs exist in the tenant's configured models
Builtin models are always allowed and do not require prior configuration

Get Default Models

GET /api/v1/models/default

Response:

{
  "code": 0,
  "data": {
    "llm_id": "gpt-4",
    "embd_id": "text-embedding-ada-002",
    "asr_id": "whisper-1",
    "img2txt_id": "gpt-4-vision-preview",
    "rerank_id": "bge-reranker-base",
    "tts_id": "tts-1"
  },
  "message": "Success"
}

…/server/routes.py): generate user API key: generates and returns an API key for a given user get user API key: returns the API key of a given user.

…, list models, set default models, list default models).

…s API.

… keys.

as-ondewo

General comments:

Some files have formatting issues like trailing spaces or not newline at the end of the file. This should be fixed by the pre-commit hooks, so please use them.
Expand Python SDK (sdk/python) to cover new endpoints.
Add documentation for new HTTP and Python SDK endpoints (docs/references).
Add support for new admin endpoints to admin CLI (admin/client/admin_client.py).
For completeness we should also add an admin endpoint for deleting API keys. I've updated the Jira ticket to also include this.
Consistently use dict and list for type hints instead of Dict and List
What's your setup for running the tests? Most of them fail for me.

admin/server/routes.py

admin/server/services.py

admin/server/routes.py

api/apps/sdk/users.py

test/testcases/test_sdk_api/test_user_models_management/conftest.py

as-ondewo

Here are some more needed changes apart from the unaddressed comments of my first review. Most of them are for the user tests which I didn't look at in depth in my first review.

test/testcases/configs.py

api/apps/sdk/users.py

pyproject.toml

as-ondewo · 2025-12-15T15:40:46Z

test/testcases/test_http_api/test_user_models_management/test_add_model.py

General comments that apply to all user tests:

use RetCode enum constants instead of integer return codes

always check for a concrete return code, not just != 0

always check for concrete messages, not just some phrases being contained in the message

never use conditional assert statements inside of if statements

as-ondewo · 2025-12-16T09:03:53Z

test/testcases/test_http_api/test_user_models_management/test_set_default_models.py

The tests are very incomplete and in some cases test things that shouldn't actually work.

setting a built-in default model:

for each type of model that has built-in models test

setting a model that exists and is configured for the current RAGFlow instance (should work)

setting a model that exists but is not configured for the current RAGFlow instance (shouldn't work)

setting a model that does not exist (should not work)

for setting multiple models simultaneously test

setting only valid models

setting a mix of valid and invalid models

setting only invalid models

the tests that you currently have pass but shouldn't because they set models that aren't configured for current RAGFlow instance

setting normal (not built-in) models:

same tests as for the built-in models

setting a model to null or "" should remove the default model, not leave it unchanged

add tests for clearing one/multiple/all models

as-ondewo · 2025-12-16T09:42:51Z

test/testcases/test_http_api/test_user_models_management/test_remove_model.py

+        models_after: Dict[str, Any] = res["data"]
+        assert "Builtin" not in models_after, "Builtin should be removed from models list"
+
+    @pytest.mark.p1


This test is redundant. Other tests already check the return code

as-ondewo · 2025-12-16T09:51:18Z

test/testcases/test_http_api/test_user_models_management/test_remove_model.py

+        # Removing non-existent factory should still succeed (no-op)
+        assert res["code"] == 0, res
+
+    @pytest.mark.p2


trying to delete a non-existent factory should fail

as-ondewo · 2025-12-16T10:50:16Z

test/testcases/test_http_api/test_user_models_management/test_list_user_models.py

+            assert len(models1[factory_name]["llm"]) == len(models2[factory_name]["llm"])
+
+    @pytest.mark.p2
+    def test_list_user_models_tags(self, HttpApiAuth):


check that the tags are actually correct

as-ondewo · 2025-12-16T10:51:54Z

test/testcases/test_http_api/test_user_models_management/test_list_user_models.py

+            assert "tags" in factory_data
+
+    @pytest.mark.p2
+    def test_list_user_models_builtin_factory(self, HttpApiAuth):


this test is redundant

as-ondewo · 2025-12-16T11:10:35Z

test/testcases/test_http_api/test_user_models_management/test_add_model.py

it shouldn't be possible to add the "Builtin" factory (should always be available)

most of the tests here are completely pointless

it is not feasible to test all possible model providers but we should at least test all possible success and failure cases for one local model and one API service

test parameter validation for all factories

test adding an individual model (not just all models from a factory)

…dd-User-API-Key-Endpoints-to-RAGFlow-Admin-Interface

as-ondewo · 2026-01-08T14:39:39Z

split up into #5 and #6

hetavi-bluexkye added 6 commits December 7, 2025 12:45

[OND211-2336]: Add 2 new endpoints to the RAGFlow admin server (admin…

9dd3471

…/server/routes.py): generate user API key: generates and returns an API key for a given user get user API key: returns the API key of a given user.

[OND211-2336]: Added API for model management(Add model, remove model…

8879efc

…, list models, set default models, list default models).

[OND211-2336]: Added tests for set default models API.

5fb6472

[OND211-2336]: Added tests for get default models and list user model…

fd8ca4b

…s API.

[OND211-2336]: Added tests for Add model and Remove model API.

93f5732

[OND211-2336]: Added tests for Generate user API key and Get user API…

f9eaf88

… keys.

hetavi-bluexkye requested review from AakashBluexkye, as-ondewo and teddius December 10, 2025 12:27

hetavi-bluexkye changed the title ~~Feature/ond211 2336 add user api key endpoints to rag flow admin interface~~ Introduce User API Key Admin Endpoints and Model Configuration SDK API Dec 10, 2025

as-ondewo requested changes Dec 12, 2025

View reviewed changes

hetavi-bluexkye added 2 commits December 15, 2025 11:32

[OND211-2336]: Added some packages.

64c62f5

[OND211-2336]: Resolved PR comments.

7273d87

as-ondewo requested changes Dec 16, 2025

View reviewed changes

hetavi-bluexkye added 9 commits December 18, 2025 01:01

[OND211-2336] Resolve PR comments.

8965423

Merge remote-tracking branch 'origin/main' into feature/OND211-2336-A…

9dfa40e

…dd-User-API-Key-Endpoints-to-RAGFlow-Admin-Interface

[OND211-2336] Fix tests.

3c40562

[OND211-2336] Fix imports.

d8c1238

Merge remote-tracking branch 'origin/main' into feature/OND211-2336-A…

168711a

…dd-User-API-Key-Endpoints-to-RAGFlow-Admin-Interface

[OND211-2336] Reolve PR comments for admin endpoints

4d2be74

[OND211-2336] Reolve PR comments

dbc0469

[OND211-2336] Fix test failures

1203696

[OND211-2336] Fix test failures

2af4ba0

hetavi-bluexkye requested a review from as-ondewo December 29, 2025 06:37

as-ondewo closed this Jan 8, 2026

Introduce User API Key Admin Endpoints and Model Configuration SDK API #4

Introduce User API Key Admin Endpoints and Model Configuration SDK API #4

Uh oh!

Conversation

hetavi-bluexkye commented Dec 10, 2025

Summary

Changes

Features

Admin API Endpoints

SDK API Endpoints (Model Management)

API Endpoints

Admin API Endpoints

Generate User API Key

Get User API Keys

SDK API Endpoints

Add Model

Remove Model

List User Models

Set Default Models

Get Default Models

Uh oh!

as-ondewo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

as-ondewo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

as-ondewo Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

as-ondewo Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

as-ondewo Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

as-ondewo Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

as-ondewo Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

as-ondewo Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

as-ondewo Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

as-ondewo commented Jan 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants