feat: introduce a /credentials API for specifying ephemeral provider-specific keys

llama_stack/apis/credentials/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+from .credentials import *  # noqa: F401 F403

llama_stack/apis/credentials/credentials.py

@@ -0,0 +1,84 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+from enum import Enum
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from llama_stack.schema_utils import json_schema_type, webmethod
+
+
+class CredentialTokenType(str, Enum):
+    """The type of credential token.
+
+    :cvar oauth2: OAuth2 token
+    :cvar api_key: API key
+
+    """
+
+    oauth2 = "oauth2"
+    api_key = "api_key"
+
+
+@json_schema_type
+class ProviderCredential(BaseModel):
+    credential_id: str
+    provider_id: str
+    token_type: CredentialTokenType
+    token: str
+
+
+@runtime_checkable
+class Credentials(Protocol):
+    """
+    Create, update and delete ephemeral provider-specific credentials.
+
+    Each provider may need optional authentication. This might be a persistent API key, or
+    a short-lived OAuth2 token. There is a single credential for each provider instance.
+
+    Credentials are ephemeral -- they may be purged after the specified TTL.
+
+    Credentials are associated with the same ABAC access attributes and permissions as other
+    resources in the system.
+
+    It is recommended to store these credentials using Envelope Encryption. The storage could
+    be a regular KVStore, but you should use a secure Key Management Service for encrypting
+    and decrypting.
+    """
+
+    @webmethod(route="/credentials", method="POST")
+    async def create_credential(
+        self, provider_id: str, token_type: CredentialTokenType, token: str, ttl_seconds: int = 3600
+    ) -> ProviderCredential:
+        """Create a new set of credentials for a given provider.
+
+        :param provider_id: The ID of the provider to create credentials for.
+        :param token_type: The type of token to create. This is provided in the API to serve as lightweight
+                           documentation / metadata for the token.
+        :param token: The token itself.
+        :param ttl_seconds: The time to live for the credential in seconds. Defaults to 3600 seconds.
+        :returns: created ProviderCredential object
+        """
+        ...
+
+    @webmethod(route="/credentials/{credential_id}", method="PUT")
+    async def update_credential(self, credential_id: str, token: str) -> ProviderCredential:
+        """Update an existing set of credentials for a given provider.
+
+        :param credential_id: The ID of the credential to update.
+        :param token: The new token to set for the credential.
+        :returns: updated ProviderCredential object
+        """
+        ...
+
+    @webmethod(route="/credentials/{credential_id}", method="DELETE")
+    async def delete_credential(self, credential_id: str) -> None:
+        """Delete a credential by its ID.
+
+        :param credential_id: The ID of the credential to delete.
+        """
+        ...

llama_stack/apis/datatypes.py

@@ -13,7 +13,6 @@ from llama_stack.schema_utils import json_schema_type
 
 @json_schema_type
 class Api(Enum):
-    providers = "providers"
     inference = "inference"
     safety = "safety"
     agents = "agents"
@@ -36,6 +35,8 @@ class Api(Enum):
     files = "files"
 
     # built-in API
+    providers = "providers"
+    credentials = "credentials"
     inspect = "inspect"
 
 

llama_stack/distribution/distribution.py

@@ -66,9 +66,23 @@ def builtin_automatically_routed_apis() -> list[AutoRoutedApiInfo]:
     ]
 
 
+def apis_provided_by_stack() -> set[Api]:
+    return {
+        Api.models,
+        Api.shields,
+        Api.vector_dbs,
+        Api.datasets,
+        Api.scoring,
+        Api.eval,
+        Api.tool_runtime,
+        Api.credentials,
+        Api.providers,
+        Api.inspect,
+    }
+
+
 def providable_apis() -> list[Api]:
-    routing_table_apis = {x.routing_table_api for x in builtin_automatically_routed_apis()}
-    return [api for api in Api if api not in routing_table_apis and api != Api.inspect and api != Api.providers]
+    return [api for api in Api if api not in apis_provided_by_stack()]
 
 
 def _load_remote_provider_spec(spec_data: dict[str, Any], api: Api) -> ProviderSpec:

llama_stack/distribution/stack.py

@@ -15,6 +15,7 @@ import yaml
 from llama_stack.apis.agents import Agents
 from llama_stack.apis.batch_inference import BatchInference
 from llama_stack.apis.benchmarks import Benchmarks
+from llama_stack.apis.credentials import Credentials
 from llama_stack.apis.datasetio import DatasetIO
 from llama_stack.apis.datasets import Datasets
 from llama_stack.apis.eval import Eval
@@ -47,7 +48,6 @@ logger = get_logger(name=__name__, category="core")
 
 
 class LlamaStack(
-    Providers,
     VectorDBs,
     Inference,
     BatchInference,
@@ -65,11 +65,13 @@ class LlamaStack(
     DatasetIO,
     Models,
     Shields,
-    Inspect,
     ToolGroups,
     ToolRuntime,
     RAGToolRuntime,
     Files,
+    Providers,
+    Credentials,
+    Inspect,
 ):
     pass