diff --git a/docs/advanced_initialization.md b/docs/advanced_initialization.md index 23cb957c..63096c06 100644 --- a/docs/advanced_initialization.md +++ b/docs/advanced_initialization.md @@ -64,9 +64,11 @@ skyflow_credentials = { 'privateKey': '' # 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() ) diff --git a/docs/api_reference.md b/docs/api_reference.md index cc5fa610..39365cf4 100644 --- a/docs/api_reference.md +++ b/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)` diff --git a/docs/auth_credentials.md b/docs/auth_credentials.md index 7db462e5..00457738 100644 --- a/docs/auth_credentials.md +++ b/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. diff --git a/docs/migrate_to_v2.md b/docs/migrate_to_v2.md index 4c94eb04..7cbae960 100644 --- a/docs/migrate_to_v2.md +++ b/docs/migrate_to_v2.md @@ -85,7 +85,7 @@ client = ( .add_vault_config({ 'vault_id': '', # Primary vault '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 diff --git a/flowvault/README.md b/flowvault/README.md index e2f92883..4afaae79 100644 --- a/flowvault/README.md +++ b/flowvault/README.md @@ -86,7 +86,7 @@ credentials = {'api_key': ''} # or 'token' / 'path' / 'credentials_str vault_config = { 'vault_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': ''} vault_config = { 'vault_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. | diff --git a/skyvault/README.md b/skyvault/README.md index 79700e31..43e61153 100644 --- a/skyvault/README.md +++ b/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,8 +753,8 @@ The SDK accepts one of several types of credentials object. ```python credentials = { - "token": "" - } + "token": "" + } ``` 3. **Service account credentials file path** @@ -762,8 +762,8 @@ The SDK accepts one of several types of credentials object. ```python credentials = { - "path": "" - } + "path": "" + } ``` 4. **Service account credentials string** @@ -773,15 +773,15 @@ 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 @@ -789,7 +789,7 @@ Generate and manage bearer tokens to authenticate API calls. This section covers #### 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)). diff --git a/skyvault/samples/README.md b/skyvault/samples/README.md index e3d20c42..a39de454 100644 --- a/skyvault/samples/README.md +++ b/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 `` strings (for example `