Skip to content

Key Vault (Secrets) API Reference

Access Azure Key Vault through the integrations namespace:

from fabias.integrations import keyvault

keyvault.client(vault_url="https://my-vault.vault.azure.net/", auth=my_auth)
password = keyvault.get("database-password")
keyvault.set("api-key", "secret-value")

Module Functions

fabias.integrations.keyvault.client(vault_url, tenant_id=None, client_id=None, client_secret=None, auth=None)

Create or configure the Key Vault client.

When called as a module-level function, sets up the singleton for convenience. Returns the client instance for both module-level and explicit multi-client use.

Parameters:

Name Type Description Default
vault_url str

Full Key Vault URL (e.g., 'https://myvault.vault.azure.net/')

 required
tenant_id Optional[str]

Azure AD tenant ID

 None
client_id Optional[str]

Application (client) ID

 None
client_secret Optional[str]

Client secret value

 None
auth Optional[AuthProvider]

Pre-configured AuthProvider (recommended)

 None

Returns:

Name Type Description
KeyVaultClient KeyVaultClient

Configured client instance

Examples:

Module-level singleton (most common):

>>> import fabias.secrets as secrets
>>> secrets.client(
...     vault_url="https://my-vault.vault.azure.net/",
...     tenant_id="your-tenant-id",
...     client_id="your-client-id",
...     client_secret="your-secret"
... )
>>> value = secrets.get("my-secret")

With pre-configured auth:

>>> from fabias._shared.auth import ServicePrincipalAuth
>>> auth = ServicePrincipalAuth(tenant_id, client_id, secret)
>>> secrets.client(vault_url="https://my-vault.vault.azure.net/", auth=auth)
>>> value = secrets.get("my-secret")

Multi-client usage:

>>> client1 = secrets.client(vault_url=vault1_url, auth=auth1)
>>> client2 = secrets.client(vault_url=vault2_url, auth=auth2)
>>> secret1 = client1.get("db-password")
>>> secret2 = client2.get("api-key")
Source code in src/fabias/integrations/keyvault/__init__.py 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
def client(
    vault_url: str,
    tenant_id: Optional[str] = None,
    client_id: Optional[str] = None,
    client_secret: Optional[str] = None,
    auth: Optional[AuthProvider] = None,
) -> KeyVaultClient:
    """
    Create or configure the Key Vault client.

    When called as a module-level function, sets up the singleton for convenience.
    Returns the client instance for both module-level and explicit multi-client use.

    Args:
        vault_url: Full Key Vault URL (e.g., 'https://myvault.vault.azure.net/')
        tenant_id: Azure AD tenant ID
        client_id: Application (client) ID
        client_secret: Client secret value
        auth: Pre-configured AuthProvider (recommended)

    Returns:
        KeyVaultClient: Configured client instance

    Examples:
        Module-level singleton (most common):

        >>> import fabias.secrets as secrets
        >>> secrets.client(
        ...     vault_url="https://my-vault.vault.azure.net/",
        ...     tenant_id="your-tenant-id",
        ...     client_id="your-client-id",
        ...     client_secret="your-secret"
        ... )
        >>> value = secrets.get("my-secret")

        With pre-configured auth:

        >>> from fabias._shared.auth import ServicePrincipalAuth
        >>> auth = ServicePrincipalAuth(tenant_id, client_id, secret)
        >>> secrets.client(vault_url="https://my-vault.vault.azure.net/", auth=auth)
        >>> value = secrets.get("my-secret")

        Multi-client usage:

        >>> client1 = secrets.client(vault_url=vault1_url, auth=auth1)
        >>> client2 = secrets.client(vault_url=vault2_url, auth=auth2)
        >>> secret1 = client1.get("db-password")
        >>> secret2 = client2.get("api-key")
    """
    global _client, _configured

    new_client = KeyVaultClient(
        vault_url=vault_url,
        auth=auth,
        tenant_id=tenant_id,
        client_id=client_id,
        client_secret=client_secret,
    )

    # Set as module-level singleton
    _client = new_client
    _configured = True

    return new_client

fabias.integrations.keyvault.get(key)

Get a secret from Azure Key Vault.

Requires secrets.client() to be called first.

Parameters:

Name Type Description Default
key str

Secret name/key in Key Vault

 required

Returns:

Name Type Description
str str

Secret value

Raises:

Type Description
FabiasError

If module not configured or secret not found

Examples:

>>> from fabias import secrets
>>> secrets.client(vault_url="https://my-vault.vault.azure.net/")
>>> password = secrets.get('database-password')
Source code in src/fabias/integrations/keyvault/__init__.py 
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
def get(key: str) -> str:
    """
    Get a secret from Azure Key Vault.

    Requires secrets.client() to be called first.

    Args:
        key: Secret name/key in Key Vault

    Returns:
        str: Secret value

    Raises:
        FabiasError: If module not configured or secret not found

    Examples:
        >>> from fabias import secrets
        >>> secrets.client(vault_url="https://my-vault.vault.azure.net/")
        >>> password = secrets.get('database-password')
    """
    return _get_client().getSecret(key)

fabias.integrations.keyvault.set(key, value)

Set a secret in Azure Key Vault.

Requires secrets.client() to be called first.

Parameters:

Name Type Description Default
key str

Secret name/key in Key Vault

 required
value str

Secret value to store

 required

Raises:

Type Description
FabiasError

If module not configured or operation fails

Examples:

>>> from fabias import secrets
>>> secrets.client(vault_url="https://my-vault.vault.azure.net/")
>>> secrets.set('api-key', 'new-api-key-value')
Source code in src/fabias/integrations/keyvault/__init__.py 
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
def set(key: str, value: str) -> None:
    """
    Set a secret in Azure Key Vault.

    Requires secrets.client() to be called first.

    Args:
        key: Secret name/key in Key Vault
        value: Secret value to store

    Raises:
        FabiasError: If module not configured or operation fails

    Examples:
        >>> from fabias import secrets
        >>> secrets.client(vault_url="https://my-vault.vault.azure.net/")
        >>> secrets.set('api-key', 'new-api-key-value')
    """
    _get_client().setSecret(key, value)

fabias.integrations.keyvault.list()

List all secrets in the Key Vault.

Returns:

Type Description
List[Dict[str, Any]]

List[Dict[str, Any]]: List of secret metadata (id, attributes, etc.)

Examples:

>>> from fabias import secrets
>>> for s in secrets.list():
...     print(s['id'])
Source code in src/fabias/integrations/keyvault/__init__.py 
310
311
312
313
314
315
316
317
318
319
320
321
322
def list() -> List[Dict[str, Any]]:
    """
    List all secrets in the Key Vault.

    Returns:
        List[Dict[str, Any]]: List of secret metadata (id, attributes, etc.)

    Examples:
        >>> from fabias import secrets
        >>> for s in secrets.list():
        ...     print(s['id'])
    """
    return _get_client().listSecrets()

fabias.integrations.keyvault.vault()

Get the configured vault URL, or None if not configured.

Source code in src/fabias/integrations/keyvault/__init__.py 
256
257
258
def vault() -> Optional[str]:
    """Get the configured vault URL, or None if not configured."""
    return _client.vaultUrl if _client else None

fabias.integrations.keyvault.reset()

Reset the module state, clearing the cached client.

Source code in src/fabias/integrations/keyvault/__init__.py 
249
250
251
252
253
def reset() -> None:
    """Reset the module state, clearing the cached client."""
    global _client, _configured
    _client = None
    _configured = False

Classes

fabias.integrations.keyvault.KeyVaultClient

Bases: BaseClient

HTTP client for Azure Key Vault REST API.

Provides authenticated access to Key Vault secrets.

Source code in src/fabias/integrations/keyvault/__init__.py 
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
class KeyVaultClient(BaseClient):
    """
    HTTP client for Azure Key Vault REST API.

    Provides authenticated access to Key Vault secrets.
    """

    KEYVAULT_SCOPE = "https://vault.azure.net/.default"

    def __init__(
        self,
        vault_url: str,
        auth: Optional[AuthProvider] = None,
        tenant_id: Optional[str] = None,
        client_id: Optional[str] = None,
        client_secret: Optional[str] = None,
    ):
        """
        Initialize the Key Vault client.

        Args:
            vault_url: Full Key Vault URL (e.g., 'https://myvault.vault.azure.net/')
            auth: Optional pre-configured AuthProvider
            tenant_id: Azure AD tenant ID (for service principal auth)
            client_id: Application client ID (for service principal auth)
            client_secret: Client secret (for service principal auth)
        """
        # Determine authentication method
        if auth:
            auth_provider = auth
        elif tenant_id and client_id and client_secret:
            auth_provider = ServicePrincipalAuth(
                tenant_id=tenant_id, client_id=client_id, client_secret=client_secret
            )
        elif runtime.isFabric:
            auth_provider = FabricAuth()
        else:
            auth_provider = AutoAuth(
                tenant_id=tenant_id, client_id=client_id, client_secret=client_secret
            )

        super().__init__(auth_provider)

        # Normalize vault URL
        if not vault_url.endswith("/"):
            vault_url = vault_url + "/"

        self._vault_url = vault_url
        self._base_uri = vault_url
        self._scope = self.KEYVAULT_SCOPE

    @property
    def vaultUrl(self) -> str:
        """Get the configured vault URL."""
        return self._vault_url

    def getSecret(self, key: str) -> str:
        """
        Retrieve a secret from Key Vault.

        In Fabric environments, attempts to use notebookutils.credentials first
        for better performance and simpler auth. Falls back to REST API.

        Args:
            key: Secret name

        Returns:
            str: Secret value

        Raises:
            FabiasError: If secret not found or retrieval fails
        """
        # In Fabric, try notebookutils first (faster, simpler auth)
        if runtime.isFabric:
            notebookutils_module = runtime.notebookutils
            if notebookutils_module and hasattr(notebookutils_module, "credentials"):
                try:
                    return cast(
                        str, notebookutils_module.credentials.getSecret(self._vault_url, key)
                    )
                except Exception:
                    # Fall through to REST API
                    pass

        # Use REST API
        url = f"secrets/{key}?api-version=7.3"
        response = self.get(url)
        data = response.json()
        value = data.get("value")
        if value is None:
            raise FabiasError(f"Secret '{key}' not found or has no value")
        return cast(str, value)

    def setSecret(self, key: str, value: str) -> None:
        """
        Set a secret in Key Vault.

        Args:
            key: Secret name
            value: Secret value

        Raises:
            FabiasError: If write fails
        """
        url = f"secrets/{key}?api-version=7.3"
        body = {"value": value}

        response = self.put(url, data=body)
        data = response.json()

        if data.get("value") == value:
            print(f'Key Vault secret "{key}" modified.')

    def listSecrets(self) -> List[Dict[str, Any]]:
        """
        List all secrets in the Key Vault.

        Returns:
            List[Dict[str, Any]]: List of secret metadata (id, attributes, etc.)
        """
        url = "secrets?api-version=7.3"
        response = self.get(url)
        data = response.json()
        return cast(List[Dict[str, Any]], data.get("value", []))

Attributes

vaultUrl property

Get the configured vault URL.

Functions

getSecret(key)

Retrieve a secret from Key Vault.

In Fabric environments, attempts to use notebookutils.credentials first for better performance and simpler auth. Falls back to REST API.

Parameters:

Name Type Description Default
key str

Secret name

 required

Returns:

Name Type Description
str str

Secret value

Raises:

Type Description
FabiasError

If secret not found or retrieval fails
Source code in src/fabias/integrations/keyvault/__init__.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def getSecret(self, key: str) -> str:
    """
    Retrieve a secret from Key Vault.

    In Fabric environments, attempts to use notebookutils.credentials first
    for better performance and simpler auth. Falls back to REST API.

    Args:
        key: Secret name

    Returns:
        str: Secret value

    Raises:
        FabiasError: If secret not found or retrieval fails
    """
    # In Fabric, try notebookutils first (faster, simpler auth)
    if runtime.isFabric:
        notebookutils_module = runtime.notebookutils
        if notebookutils_module and hasattr(notebookutils_module, "credentials"):
            try:
                return cast(
                    str, notebookutils_module.credentials.getSecret(self._vault_url, key)
                )
            except Exception:
                # Fall through to REST API
                pass

    # Use REST API
    url = f"secrets/{key}?api-version=7.3"
    response = self.get(url)
    data = response.json()
    value = data.get("value")
    if value is None:
        raise FabiasError(f"Secret '{key}' not found or has no value")
    return cast(str, value)

setSecret(key, value)

Set a secret in Key Vault.

Parameters:

Name Type Description Default
key str

Secret name

 required
value str

Secret value

 required

Raises:

Type Description
FabiasError

If write fails
Source code in src/fabias/integrations/keyvault/__init__.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
def setSecret(self, key: str, value: str) -> None:
    """
    Set a secret in Key Vault.

    Args:
        key: Secret name
        value: Secret value

    Raises:
        FabiasError: If write fails
    """
    url = f"secrets/{key}?api-version=7.3"
    body = {"value": value}

    response = self.put(url, data=body)
    data = response.json()

    if data.get("value") == value:
        print(f'Key Vault secret "{key}" modified.')

listSecrets()

List all secrets in the Key Vault.

Returns:

Type Description
List[Dict[str, Any]]

List[Dict[str, Any]]: List of secret metadata (id, attributes, etc.)
Source code in src/fabias/integrations/keyvault/__init__.py 
148
149
150
151
152
153
154
155
156
157
158
def listSecrets(self) -> List[Dict[str, Any]]:
    """
    List all secrets in the Key Vault.

    Returns:
        List[Dict[str, Any]]: List of secret metadata (id, attributes, etc.)
    """
    url = "secrets?api-version=7.3"
    response = self.get(url)
    data = response.json()
    return cast(List[Dict[str, Any]], data.get("value", []))