docs: Fix Python SDK credential examples, env default, and stale links

docs/advanced_initialization.md

@@ -64,9 +64,11 @@ skyflow_credentials = {
     'privateKey': '<YOUR_PRIVATE_KEY>'    # Replace with your Private Key.
 }
 
-# Step 4: Convert the JSON object to a string and use it as credentials.
+# Step 4: Convert the JSON object to a string and wrap it as a `credentials_string` credentials dict.
 # This approach allows the use of dynamically generated or pre-configured credentials.
-credentials_string = json.dumps(skyflow_credentials)  # Converts JSON object to string for use as credentials.
+common_credentials = {
+    'credentials_string': json.dumps(skyflow_credentials)  # Converts JSON object to string for use as credentials.
+}
 
 # Step 5: Define secondary credentials (API key-based authentication as an example).
 # Demonstrates a different type of authentication mechanism for Skyflow vaults.
@@ -104,7 +106,7 @@ skyflow_client = (
     .add_vault_config(primary_vault_config)   # Add the primary vault configuration.
     .add_vault_config(secondary_vault_config) # Add the secondary vault configuration.
     .add_vault_config(tertiary_vault_config)  # Add the tertiary vault configuration.
-    .add_skyflow_credentials(skyflow_credentials)  # Add JSON-formatted credentials if applicable.
+    .add_skyflow_credentials(common_credentials)  # Add JSON-formatted credentials if applicable.
     .set_log_level(LogLevel.ERROR)  # Set log level for debugging or monitoring purposes.
     .build()
 )

docs/api_reference.md

@@ -1,6 +1,6 @@
 # API Reference
 
-A reference for the public Skyflow Python SDK surface: client-management methods, request and response objects, enums, Detect helper classes, and service-account functions. For task-oriented usage and examples, see the [README](../README.md).
+A reference for the public Skyflow Python SDK surface: client-management methods, request and response objects, enums, Detect helper classes, and service-account functions. For task-oriented usage and examples, see the [skyvault README](../skyvault/README.md).
 
 All attributes, parameters, and enum values below are taken directly from the SDK source.
 
@@ -380,11 +380,11 @@ Vault hostnames per environment (used internally; exported for reference).
 
 ### `LogLevel`
 
-`DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`. See [Logging](../README.md#logging).
+`DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`. See [Logging](../skyvault/README.md#logging).
 
 ### `RedactionType`
 
-How retrieved data is displayed. Values: `PLAIN_TEXT`, `MASKED`, `DEFAULT`, `REDACTED`. See [Redaction Types](../README.md#redaction-types).
+How retrieved data is displayed. Values: `PLAIN_TEXT`, `MASKED`, `DEFAULT`, `REDACTED`. See [Redaction Types](../skyvault/README.md#redaction-types).
 
 ### `TokenMode`
 
@@ -476,7 +476,7 @@ Wrapper around the processed file returned in `DeidentifyFileResponse.file`.
 
 ## Service account functions
 
-Importable from `skyflow.service_account`. See [Authentication & authorization](../README.md#authentication--authorization) for `generate_bearer_token`, `generate_bearer_token_from_creds`, and `generate_signed_data_tokens`.
+Importable from `skyflow.service_account`. See [Authentication & authorization](../skyvault/README.md#authentication--authorization) for `generate_bearer_token`, `generate_bearer_token_from_creds`, and `generate_signed_data_tokens`.
 
 ### `is_expired(token, logger=None)`
 

docs/auth_credentials.md

@@ -1,6 +1,6 @@
 # Authentication credentials options
 
-> **Note:** Only one type of credential can be used at a time. If multiple credentials are provided, the last one added takes precedence.
+> **Note:** Only one type of credential can be used at a time. If the `credentials` dict has more than one of `api_key`, `token`, `path`, or `credentials_string`, the SDK raises a `SkyflowError`.
 
 1. **API keys**
 
@@ -40,10 +40,12 @@
 
    ```python
    credentials = {
-    "credentials_string": os.getenv("SKYFLOW_CREDENTIALS_JSON_STRING") 
+    "credentials_string": os.getenv("MY_APP_CREDENTIALS_JSON")
     }
    ```
 
+   `MY_APP_CREDENTIALS_JSON` is an example name for a variable you choose yourself; it's unrelated to the `SKYFLOW_CREDENTIALS` variable the SDK reads automatically, described next.
+
 5. **Environment variables**
 
    If no credentials are explicitly provided, the SDK automatically looks for the `SKYFLOW_CREDENTIALS` environment variable. This variable must contain a JSON string like one of the examples above.

docs/migrate_to_v2.md

@@ -85,7 +85,7 @@ client = (
     .add_vault_config({
            'vault_id': '<VAULT_ID>', # Primary vault
            'cluster_id': '<CLUSTER_ID>', # ID from your vault URL e.g., https://{clusterId}.vault.skyflowapis.com
-           'env': Env.PROD, # Env by default it is set to PROD
+           'env': Env.PROD, # Set the environment (DEV, SANDBOX, PROD, or STAGE)
            'credentials': credentials # Individual credentials
     })
     .add_skyflow_credentials(credentials) # Skyflow credentials will be used if no individual credentials are passed
@@ -102,11 +102,11 @@ client = (
 ### Request & Response Structure
 
 In v2, with the introduction of constructor parameters, you can now pass parameters to `InsertRequest`. This request needs 
-- **`table_name`**: The name of the table.
+- **`table`**: The name of the table.
 - **`values`**: An array of objects containing the data to be inserted.
 The response will be of type `InsertResponse` class, which contains `inserted_fields` and errors.
 
-**Note:** Similar patterns apply to other operations like Get, Update, Delete. See the [README](../README.md) for complete examples.
+**Note:** Similar patterns apply to other operations like Get, Update, Delete. See the [skyvault README](../skyvault/README.md) for complete examples.
 
 #### v1 (Old): Request Building
 

flowvault/README.md

@@ -86,7 +86,7 @@ credentials = {'api_key': '<API_KEY>'}  # or 'token' / 'path' / 'credentials_str
 vault_config = {
     'vault_id': '<VAULT_ID>',
     'cluster_id': '<CLUSTER_ID>',   # part of the vault URL: https://{cluster_id}.vault.skyflowapis.com
-    'env': Env.PROD,                # DEV, STAGE, SANDBOX, or PROD (default)
+    'env': Env.PROD,                # DEV, STAGE, SANDBOX, or PROD
     'credentials': credentials,
 }
 
@@ -114,7 +114,7 @@ Requests are authorized with Skyflow credentials that you attach to the vault co
 
 ## Credential types
 
-Set **exactly one** of the following keys on the `credentials` dict. If you set more than one, the resolution is undefined — pick one.
+Set **exactly one** of the following keys on the `credentials` dict. If you set more than one, the SDK raises a `SkyflowError` — pick one.
 
 | Key | What it is |
 |---|---|
@@ -267,7 +267,7 @@ credentials = {'path': '<PATH_TO_CREDENTIALS_JSON>'}
 vault_config = {
     'vault_id': '<VAULT_ID>',
     'cluster_id': '<CLUSTER_ID>',
-    'env': Env.PROD,            # DEV, STAGE, SANDBOX, or PROD (default)
+    'env': Env.PROD,            # DEV, STAGE, SANDBOX, or PROD
     'credentials': credentials,
     # Optional: vault-level HTTP overrides
     'timeout': 120,             # overall call timeout, in seconds
@@ -294,7 +294,7 @@ The vault config is a plain dict:
 |---|---|---|
 | `vault_id` | required | The vault's ID. |
 | `cluster_id` | required | The cluster portion of the vault URL — `https://{cluster_id}.vault.skyflowapis.com`. |
-| `env` | optional | `Env.DEV`, `Env.STAGE`, `Env.SANDBOX`, or `Env.PROD`. Defaults to `PROD`. |
+| `env` | required | `Env.DEV`, `Env.STAGE`, `Env.SANDBOX`, or `Env.PROD`. |
 | `credentials` | optional | Credentials for this vault. Falls back to client-wide credentials, then `SKYFLOW_CREDENTIALS`. |
 | `vault_url` | optional | Full vault URL, when it cannot be derived from `cluster_id` and `env`. |
 | `timeout` | optional | Overall call timeout in seconds, including retries. |

skyvault/README.md

@@ -1,6 +1,6 @@
 # Skyflow Python SDK
 
-> **This is the current, recommended version of the Skyflow SDK.** V2.1.0 brings flexible auth, multi-vault support, native data types, and rich error diagnostics.
+> **This is the current, recommended version of the Skyflow SDK.** V2 brings flexible auth, multi-vault support, native data types, and rich error diagnostics.
 >
 > Migrating from v1? See the **[Migration Guide](https://github.com/skyflowapi/skyflow-python/blob/main/docs/migrate_to_v2.md)** for step-by-step instructions. V1 is in maintenance mode and will reach End of Life on October 31, 2026.
 
@@ -103,7 +103,7 @@ To run the examples below, you need a Skyflow account and a few values from the
 |-------|------------------|
 | `vault_id` | Your vault's details page in Skyflow Studio. |
 | `cluster_id` | The first segment of your vault URL: `https://{cluster_id}.vault.skyflowapis.com`. |
-| `env` | The environment your vault runs in — `Env.PROD`, `Env.SANDBOX`, `Env.DEV`, or `Env.STAGE` (defaults to `PROD`). |
+| `env` | The environment your vault runs in — `Env.PROD`, `Env.SANDBOX`, `Env.DEV`, or `Env.STAGE`. |
 | Credentials | Create a **service account** in Studio. Choose **API key** during creation for the simplest setup, or download the service-account `credentials.json` for token-based auth. See [Authentication & authorization](#authentication--authorization). |
 
 The quickstart below assumes a table named `table1` with `card_number` and `cardholder_name` columns. Create a matching table (or adjust the table/column names to your schema) in your vault before running it. See the [Skyflow docs](https://docs.skyflow.com/) for creating vaults, tables, and service accounts.
@@ -687,7 +687,7 @@ Get Detect Run Response: DeidentifyFileResponse(file_base64=None, file=None, ...
 
 ## Connections
 
-Securely send and receive data between your systems and first- or third-party services using Skyflow Connections. The [connections](https://github.com/skyflowapi/skyflow-python/tree/v2/skyflow/vault/connection) module invokes both inbound and/or outbound connections.
+Securely send and receive data between your systems and first- or third-party services using Skyflow Connections. The [connections](https://github.com/skyflowapi/skyflow-python/tree/main/skyvault/skyflow/vault/connection) module invokes both inbound and outbound connections.
 
 - **Inbound connections**: Act as intermediaries between your client and server, tokenizing sensitive data before it reaches your backend, ensuring downstream services handle only tokenized data.
 - **Outbound connections**: Enable secure extraction of data from the vault and transfer it to third-party services via your backend server, such as processing checkout or card issuance flows.
@@ -753,17 +753,17 @@ The SDK accepts one of several types of credentials object.
 
    ```python
    credentials = {
-    "token": "<YOUR_BEARER_TOKEN>"
-    }
+       "token": "<YOUR_BEARER_TOKEN>"
+   }
    ```
 
 3. **Service account credentials file path**
    The file path pointing to a JSON file containing credentials for a service account. Use when credentials are managed externally or stored in secure file systems.
 
    ```python
    credentials = {
-    "path": "<YOUR_CREDENTIALS_FILE_PATH>"
-    }
+       "path": "<YOUR_CREDENTIALS_FILE_PATH>"
+   }
    ```
 
 4. **Service account credentials string**
@@ -773,23 +773,23 @@ The SDK accepts one of several types of credentials object.
    import os
 
    credentials = {
-    "credentials_string": os.getenv("SKYFLOW_CREDENTIALS")
-    }
+       "credentials_string": os.getenv("SKYFLOW_CREDENTIALS")
+   }
    ```
 
 5. **Environment variables**
    If no credentials are explicitly provided, the SDK automatically looks for the SKYFLOW_CREDENTIALS environment variable. Use to avoid hardcoding credentials in source code. This variable must return an object like one of the examples above.
 
 > [!NOTE]
-> Only one type of credential can be used at a time. If multiple credentials are provided, the last one added will take precedence.
+> Only one type of credential can be used at a time. If the `credentials` dict has more than one of `api_key`, `token`, `path`, or `credentials_string`, the SDK raises a `SkyflowError`.
 
 ### Generate bearer tokens for authentication & authorization
 
 Generate and manage bearer tokens to authenticate API calls. This section covers options for scoping to certain roles, passing context, and signing data tokens.
 
 #### Generate a bearer token
 
-Generate service account tokens using the [Service Account](https://github.com/skyflowapi/skyflow-python/tree/main/skyflow/service_account) Python package with a service account credentials file provided when a service account is created. Tokens generated by this module are valid for 60 minutes and can be used to make API calls to the [Data](https://docs.skyflow.com/record/) and [Management](https://docs.skyflow.com/management/) APIs, depending on the permissions assigned to the service account.
+Generate service account tokens using the [Service Account](https://github.com/skyflowapi/skyflow-python/tree/main/skyvault/skyflow/service_account) Python package with a service account credentials file provided when a service account is created. Tokens generated by this module are valid for 60 minutes and can be used to make API calls to the [Data](https://docs.skyflow.com/record/) and [Management](https://docs.skyflow.com/management/) APIs, depending on the permissions assigned to the service account.
 
 ##### `generate_bearer_token(filepath)`
 
@@ -807,7 +807,7 @@ print("Bearer Token:", token)
 Alternatively, you can also send the entire credentials as string by using `generate_bearer_token_from_creds(string)`.
 
 > [!TIP]
-> See the full example in the samples directory: [token_generation_example.py](https://github.com/skyflowapi/skyflow-python/blob/main/samples/service_account/token_generation_example.py)
+> See the full example in the samples directory: [token_generation_example.py](https://github.com/skyflowapi/skyflow-python/blob/main/skyvault/samples/service_account/token_generation_example.py)
 
 #### Generate bearer tokens scoped to certain roles
 
@@ -1002,7 +1002,7 @@ Most first-run problems come from configuration mismatches. Every error raised b
 | `404` referencing a table or column | Table/column doesn't exist or name mismatch | Confirm the table and column names match your vault schema exactly (case-sensitive). |
 | Vault not found / 404 with a valid `cluster_id` | Wrong `vault_id` | Copy `vault_id` from the vault's details page in Skyflow Studio. |
 | `Authentication failed. Bearer token is expired.` | Token expired between verification and the API call | Retry the request; the SDK regenerates the token. See [Bearer token expiration edge cases](#bearer-token-expiration-edge-cases). |
-| Unexpected credential is used | Multiple credentials provided | Only one credential type is used at a time; the last one added takes precedence. Provide exactly one. |
+| `SkyflowError`: "Multiple credentials provided" | More than one of `api_key`, `token`, `path`, or `credentials_string` set in the `credentials` dict | Provide exactly one credential type. |
 | `RequestMethod.PATCH` raises `AttributeError` | `PATCH` is not a supported connection method | Use `GET`, `POST`, `PUT`, or `DELETE` (see [`RequestMethod`](../docs/api_reference.md#requestmethod)). |
 
 If you're stuck, set `set_log_level(LogLevel.DEBUG)` during development for detailed SDK logs (see [Logging](#logging)).

skyvault/samples/README.md

@@ -1,6 +1,6 @@
 # Skyflow Python SDK — Samples
 
-Runnable examples for the Skyflow Python SDK, grouped by area. Start with the [README](../README.md) and [API Reference](../docs/api_reference.md) for full documentation.
+Runnable examples for the Skyflow Python SDK, grouped by area. Start with the [README](../README.md) and [API Reference](../../docs/api_reference.md) for full documentation.
 
 ## Prerequisites
 
@@ -18,7 +18,7 @@ The samples ship with inline `<PLACEHOLDER>` strings (for example `<YOUR_VAULT_I
 ## Run a sample
 
 ```bash
-python samples/vault_api/insert_records.py
+python skyvault/samples/vault_api/insert_records.py
 ```
 
 ## What's here