Support for Multiple API Keys

Multiple API keys can be associated with the container at startup as a means of authentication. The use of multiple API keys enables finer-grained access management and improved auditing and attribution of requests

If PRIVATE_AI_AUTHENTICATION_ENABLED is set to TRUE, the service will reject any requests that do not carry a valid API Key in the "Authorization: Bearer" header field. Requests are authenticated only if the presented API key matches an active key loaded from the secrets file.

API keys are stored in plain text with a unique ID, alias, and an active status in a JSON or YAML file on a mounted read-only file system. To revoke a key, set its active field to false. Deleting an entry from the list has the same effect. The service will automatically stop accepting the revoked key on the next file reload; no restart is required.

When using the database as a client through the use of the PL/SQL functions UTL_TO_EMBEDDING, UTL_TO_EMBEDDINGS, UTL_TO_RERANK, or UTL_TO_TEXT_GENERATION, you must first create a credential containing a valid key using the CREATE_CREDENTIAL procedure. This credential is then referenced when registering the Private AI Services Container as a provider for generating embeddings.

Note:

Updates to the secrets file should use atomic write or rename to avoid partial updates.

Note:

You can optionally use the PRIVATE_AI_MAX_ACTIVE_API_KEYS and PRIVATE_AI_API_KEY_ID_MAX_LENGTH environment variables to specify limits on the number of active keys and the normalized key_id length, respectively. For more information, see Private AI Environment Variables.

Example: Configure Multiple API Keys in a Container

1. Create an api-keys.json file with the following content:

   [
     { "key_id": "client1", "alias": "ServiceA", "key": "abc123", "active": true },
     { "key_id": "client2", "alias": "ServiceB", "key": "xyz789", "active": false }
   ]

   The key_id is required for active records and must conform to the following rules:

   • For active records, the value cannot be blank and must be unique among active records.
   • Colons and control characters are not permitted.

   Inactive records are ignored by authentication.

2. Mount the file into the container and point the service to it:

   podman run \
     -v $(pwd)/api-keys.json:/run/secrets/api-keys.json:ro \
     -e PRIVATE_AI_APIKEY_FILE=api-keys.json \
     <image-name>

   Alternatively, create a Podman secret from the same file:

   podman secret create api-keys ./api-keys.json
   
   podman run \
     --secret api-keys,target=/run/secrets/api-keys.json \
     -e PRIVATE_AI_APIKEY_FILE=api-keys.json \
     <image-name>