From b43cdaaed54b78dd073717a5ab4ab51bc54ee298 Mon Sep 17 00:00:00 2001 From: Ashwin Bharambe Date: Tue, 20 May 2025 13:51:28 -0700 Subject: [PATCH] updates --- docs/_static/llama-stack-spec.html | 180 ++++++++------------ docs/_static/llama-stack-spec.yaml | 145 +++++++--------- llama_stack/apis/credentials/credentials.py | 55 +++--- 3 files changed, 167 insertions(+), 213 deletions(-) diff --git a/docs/_static/llama-stack-spec.html b/docs/_static/llama-stack-spec.html index 3b9afed6d..974f20754 100644 --- a/docs/_static/llama-stack-spec.html +++ b/docs/_static/llama-stack-spec.html @@ -518,14 +518,45 @@ } }, "/v1/credentials": { + "get": { + "responses": { + "200": { + "description": "A list of all credentials for the current user.", + "content": { + "application/jsonl": { + "schema": { + "$ref": "#/components/schemas/CredentialListItem" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Credentials" + ], + "description": "Get all credentials for the current user.", + "parameters": [] + }, "post": { "responses": { "200": { - "description": "created ProviderCredential object", + "description": "The ID of the created credential.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ProviderCredential" + "type": "string" } } } @@ -877,57 +908,6 @@ } }, "/v1/credentials/{credential_id}": { - "post": { - "responses": { - "200": { - "description": "updated ProviderCredential object", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ProviderCredential" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest400" - }, - "429": { - "$ref": "#/components/responses/TooManyRequests429" - }, - "500": { - "$ref": "#/components/responses/InternalServerError500" - }, - "default": { - "$ref": "#/components/responses/DefaultError" - } - }, - "tags": [ - "Credentials" - ], - "description": "Update an existing set of credentials for a given provider.", - "parameters": [ - { - "name": "credential_id", - "in": "path", - "description": "The ID of the credential to update.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateCredentialRequest" - } - } - }, - "required": true - } - }, "delete": { "responses": { "200": { @@ -6754,8 +6734,8 @@ "token_type": { "type": "string", "enum": [ - "oauth2", - "api_key" + "oauth2_authorization_code", + "access_token" ], "description": "The type of token to create. This is provided in the API to serve as lightweight documentation / metadata for the token." }, @@ -6763,9 +6743,13 @@ "type": "string", "description": "The token itself." }, + "nonce": { + "type": "string", + "description": "The nonce is required when the token type is oauth2_authorization_code." + }, "ttl_seconds": { "type": "integer", - "description": "The time to live for the credential in seconds. Defaults to 3600 seconds." + "description": "The time to live for the credential in seconds. Defaults to 3600 seconds. When token_type is oauth2_authorization_code, the TTL is ignored and is obtained from the provider when exchanging the code for an access token." } }, "additionalProperties": false, @@ -6777,42 +6761,6 @@ ], "title": "CreateCredentialRequest" }, - "ProviderCredential": { - "type": "object", - "properties": { - "credential_id": { - "type": "string" - }, - "provider_id": { - "type": "string" - }, - "token_type": { - "type": "string", - "enum": [ - "oauth2", - "api_key" - ], - "title": "CredentialTokenType", - "description": "The type of credential token." - }, - "token": { - "type": "string" - }, - "expires_at": { - "type": "string", - "format": "date-time" - } - }, - "additionalProperties": false, - "required": [ - "credential_id", - "provider_id", - "token_type", - "token", - "expires_at" - ], - "title": "ProviderCredential" - }, "OpenAIResponseInput": { "oneOf": [ { @@ -8570,6 +8518,38 @@ ], "title": "OpenAICompletionWithInputMessages" }, + "CredentialListItem": { + "type": "object", + "properties": { + "credential_id": { + "type": "string" + }, + "provider_id": { + "type": "string" + }, + "token_type": { + "type": "string", + "enum": [ + "oauth2_authorization_code", + "access_token" + ], + "title": "CredentialTokenType", + "description": "The type of credential token." + }, + "expires_at": { + "type": "string", + "format": "date-time" + } + }, + "additionalProperties": false, + "required": [ + "credential_id", + "provider_id", + "token_type", + "expires_at" + ], + "title": "CredentialListItem" + }, "DataSource": { "oneOf": [ { @@ -13134,20 +13114,6 @@ "title": "SyntheticDataGenerationResponse", "description": "Response from the synthetic data generation. Batch of (prompt, response, score) tuples that pass the threshold." }, - "UpdateCredentialRequest": { - "type": "object", - "properties": { - "token": { - "type": "string", - "description": "The new token to set for the credential." - } - }, - "additionalProperties": false, - "required": [ - "token" - ], - "title": "UpdateCredentialRequest" - }, "VersionInfo": { "type": "object", "properties": { @@ -13246,7 +13212,7 @@ }, { "name": "Credentials", - "description": "Each provider may need optional authentication. This might be a persistent API key, or\na short-lived OAuth2 token. There is a single credential for each provider instance.\n\nCredentials are ephemeral -- they may be purged after the specified TTL.\n\nCredentials are associated with the same ABAC access attributes and permissions as other\nresources in the system.\n\nIt is recommended to store these credentials using Envelope Encryption. The storage could\nbe a regular KVStore, but you should use a secure Key Management Service for encrypting\nand decrypting.", + "description": "Each provider may need optional authentication. This might be a persistent API key, a short-lived OAuth2\naccess token or a refreshable OAuth2 token. There is a single credential for each provider instance.\n\nCredentials are ephemeral -- they may be purged after the specified TTL.\n\nCredentials are associated with the logged in user. If no user is logged in, the credentials\nare associated with the anonymous user.\n\nIt is recommended to store these credentials using Envelope Encryption. The storage could\nbe a regular KVStore, but you should use a secure Key Management Service for encrypting\nand decrypting.", "x-displayName": "Create, update and delete ephemeral provider-specific credentials." }, { diff --git a/docs/_static/llama-stack-spec.yaml b/docs/_static/llama-stack-spec.yaml index 0ae699c15..d8f715a63 100644 --- a/docs/_static/llama-stack-spec.yaml +++ b/docs/_static/llama-stack-spec.yaml @@ -349,14 +349,38 @@ paths: $ref: '#/components/schemas/CreateAgentTurnRequest' required: true /v1/credentials: + get: + responses: + '200': + description: >- + A list of all credentials for the current user. + content: + application/jsonl: + schema: + $ref: '#/components/schemas/CredentialListItem' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Credentials + description: >- + Get all credentials for the current user. + parameters: [] post: responses: '200': - description: created ProviderCredential object + description: The ID of the created credential. content: application/json: schema: - $ref: '#/components/schemas/ProviderCredential' + type: string '400': $ref: '#/components/responses/BadRequest400' '429': @@ -600,41 +624,6 @@ paths: schema: type: string /v1/credentials/{credential_id}: - post: - responses: - '200': - description: updated ProviderCredential object - content: - application/json: - schema: - $ref: '#/components/schemas/ProviderCredential' - '400': - $ref: '#/components/responses/BadRequest400' - '429': - $ref: >- - #/components/responses/TooManyRequests429 - '500': - $ref: >- - #/components/responses/InternalServerError500 - default: - $ref: '#/components/responses/DefaultError' - tags: - - Credentials - description: >- - Update an existing set of credentials for a given provider. - parameters: - - name: credential_id - in: path - description: The ID of the credential to update. - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateCredentialRequest' - required: true delete: responses: '200': @@ -4780,18 +4769,24 @@ components: token_type: type: string enum: - - oauth2 - - api_key + - oauth2_authorization_code + - access_token description: >- The type of token to create. This is provided in the API to serve as lightweight documentation / metadata for the token. token: type: string description: The token itself. + nonce: + type: string + description: >- + The nonce is required when the token type is oauth2_authorization_code. ttl_seconds: type: integer description: >- The time to live for the credential in seconds. Defaults to 3600 seconds. + When token_type is oauth2_authorization_code, the TTL is ignored and is + obtained from the provider when exchanging the code for an access token. additionalProperties: false required: - provider_id @@ -4799,33 +4794,6 @@ components: - token - ttl_seconds title: CreateCredentialRequest - ProviderCredential: - type: object - properties: - credential_id: - type: string - provider_id: - type: string - token_type: - type: string - enum: - - oauth2 - - api_key - title: CredentialTokenType - description: The type of credential token. - token: - type: string - expires_at: - type: string - format: date-time - additionalProperties: false - required: - - credential_id - - provider_id - - token_type - - token - - expires_at - title: ProviderCredential OpenAIResponseInput: oneOf: - $ref: '#/components/schemas/OpenAIResponseOutputMessageWebSearchToolCall' @@ -6069,6 +6037,30 @@ components: - model - input_messages title: OpenAICompletionWithInputMessages + CredentialListItem: + type: object + properties: + credential_id: + type: string + provider_id: + type: string + token_type: + type: string + enum: + - oauth2_authorization_code + - access_token + title: CredentialTokenType + description: The type of credential token. + expires_at: + type: string + format: date-time + additionalProperties: false + required: + - credential_id + - provider_id + - token_type + - expires_at + title: CredentialListItem DataSource: oneOf: - $ref: '#/components/schemas/URIDataSource' @@ -9117,16 +9109,6 @@ components: description: >- Response from the synthetic data generation. Batch of (prompt, response, score) tuples that pass the threshold. - UpdateCredentialRequest: - type: object - properties: - token: - type: string - description: The new token to set for the credential. - additionalProperties: false - required: - - token - title: UpdateCredentialRequest VersionInfo: type: object properties: @@ -9218,18 +9200,19 @@ tags: - name: Credentials description: >- Each provider may need optional authentication. This might be a persistent API - key, or + key, a short-lived OAuth2 - a short-lived OAuth2 token. There is a single credential for each provider instance. + access token or a refreshable 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 + Credentials are associated with the logged in user. If no user is logged in, + the credentials - resources in the system. + are associated with the anonymous user. It is recommended to store these credentials using Envelope Encryption. The diff --git a/llama_stack/apis/credentials/credentials.py b/llama_stack/apis/credentials/credentials.py index 8b15ab67c..8ab4f7ab6 100644 --- a/llama_stack/apis/credentials/credentials.py +++ b/llama_stack/apis/credentials/credentials.py @@ -10,27 +10,26 @@ from typing import Protocol, runtime_checkable from pydantic import BaseModel, Field -from llama_stack.schema_utils import json_schema_type, webmethod +from llama_stack.schema_utils import webmethod class CredentialTokenType(str, Enum): """The type of credential token. - :cvar oauth2: OAuth2 token - :cvar api_key: API key + :cvar oauth2_authorization_code: OAuth2 authorization code. Used to exchange for an access token (and optionally, refresh token). + This should be provided once the client receives the OAuth2 callback. + :cvar access_token: An opaque OAuth2 / JWT access token. Often what is vended as a "API key". """ - oauth2 = "oauth2" - api_key = "api_key" + oauth2_authorization_code = "oauth2_authorization_code" + access_token = "access_token" -@json_schema_type -class ProviderCredential(BaseModel): +class CredentialListItem(BaseModel): credential_id: str provider_id: str token_type: CredentialTokenType - token: str expires_at: datetime = Field(description="The time at which the credential expires. In UTC.") @@ -39,13 +38,13 @@ 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. + Each provider may need optional authentication. This might be a persistent API key, a short-lived OAuth2 + access token or a refreshable 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. + Credentials are associated with the logged in user. If no user is logged in, the credentials + are associated with the anonymous user. 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 @@ -54,26 +53,24 @@ class Credentials(Protocol): @webmethod(route="/credentials", method="POST") async def create_credential( - self, provider_id: str, token_type: CredentialTokenType, token: str, ttl_seconds: int = 3600 - ) -> ProviderCredential: + self, + provider_id: str, + token_type: CredentialTokenType, + token: str, + nonce: str | None = None, + ttl_seconds: int = 3600, + ) -> str: """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 nonce: The nonce is required when the token type is oauth2_authorization_code. :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 + When token_type is oauth2_authorization_code, the TTL is ignored and is obtained + from the provider when exchanging the code for an access token. + :returns: The ID of the created credential. """ ... @@ -84,3 +81,11 @@ class Credentials(Protocol): :param credential_id: The ID of the credential to delete. """ ... + + @webmethod(route="/credentials", method="GET") + async def get_credentials(self) -> list[CredentialListItem]: + """Get all credentials for the current user. + + :returns: A list of all credentials for the current user. + """ + ...