From 034a8861b0ec5ce1627d7593539d66ff0ddbd3f4 Mon Sep 17 00:00:00 2001 From: saileshwar-skyflow Date: Tue, 9 Jun 2026 14:32:15 +0530 Subject: [PATCH] SK-2706: fix README/samples gaps and add API reference doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix DetokenizeRequest code blocks to use DetokenizeData struct - Fix UpdateRequest to use Data map instead of Id/Values - Fix GetRequest/GetOptions: move ColumnName/ColumnValues to GetOptions - Fix WithVaultConfig → WithVaults in custom headers example - Add InsertOptions, DetokenizeOptions, GetOptions field tables - Add Client management section with all 13 Skyflow instance methods - Add SkyflowError methods table and MaskingMethod/Transcription enums - Fix signed_token_generation.go: pass credString not filePath to GenerateSignedDataTokensFromCreds - Add docs/api_reference.md covering full Go SDK v2 public API surface Co-Authored-By: Claude Sonnet 4.6 --- README.md | 298 ++++-- docs/api_reference.md | 896 ++++++++++++++++++ .../serviceaccount/signed_token_generation.go | 10 +- 3 files changed, 1123 insertions(+), 81 deletions(-) create mode 100644 docs/api_reference.md diff --git a/README.md b/README.md index c18842a4..129e447c 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,11 @@ The Skyflow Go SDK is designed to help with integrating Skyflow into a go backen - [Get Run](#get-run) - [Connections](#connections) - [Invoke a Connection](#invoke-connection) +- [Client management](#client-management) + - [Vault management](#vault-management) + - [Connection management](#connection-management) + - [Credential management](#credential-management) + - [Log level management](#log-level-management) - [Authentication & authorization](#authentication--authorization) - [Types of credentials](#types-of-credentials) - [Generate bearer tokens for authentication & authorization](#generate-bearer-tokens-for-authentication--authorization) @@ -309,6 +314,18 @@ func main() { } ``` +**`InsertOptions` fields:** + +| Field | Type | Description | +|-------|------|-------------| +| `ReturnTokens` | `bool` | Return tokens for the inserted records. | +| `Upsert` | `string` | Column name to use for upsert (must be unique in schema). | +| `ContinueOnError` | `bool` | Continue inserting remaining records if one fails. | +| `Homogeneous` | `bool` | Set to `true` when all records in the batch have identical fields; enables a more efficient bulk-insert path. | +| `TokenMode` | `BYOT` | Bring-Your-Own-Token mode: `ENABLE`, `DISABLE`, `ENABLE_STRICT`. | +| `Tokens` | `[]map[string]interface{}` | BYOT tokens to associate with inserted records. | +| `CustomHeaders` | `map[CustomHeaderKey]string` | Request-level custom headers for this call. | + #### Insert example with `ContinueOnError` option Set the `ContinueOnError` flag to `true` to allow insert operations to proceed despite encountering partial errors. @@ -511,16 +528,14 @@ func main() { // Configure the vaults and Skyflow client ctx := context.TODO() // Create a context for the detokenization operation. - // Step 1: Initialize a list of tokens to be detokenized (replace with actual tokens) - tokens := []string{"", ""} // Replace with actual token values. - - // Step 2: Create the DetokenizeRequest object with the tokens and redaction type + // Step 1: Create the DetokenizeRequest with tokens and per-token redaction types detokenizeRequest := common.DetokenizeRequest{ - ReturnTokens: tokens, // Provide the list of tokens to be detokenized - RedactionType: common.PLAIN_TEXT, // Specify how the detokenized data should be returned (plain text) - ContinueOnError: true, // Continue even if one token cannot be detokenized + DetokenizeData: []common.DetokenizeData{ + {Token: "", RedactionType: common.PLAIN_TEXT}, + {Token: "", RedactionType: common.PLAIN_TEXT}, + }, } - // Step 2: Create the DetokenizeOptions object with the ContinueOnError + // Step 2: Create the DetokenizeOptions object with ContinueOnError options := common.DetokenizeOptions{ ContinueOnError: true, // Continue even if one token cannot be detokenized. } @@ -544,8 +559,16 @@ func main() { } ``` +**`DetokenizeOptions` fields:** + +| Field | Type | Description | +|-------|------|-------------| +| `ContinueOnError` | `bool` | Continue detokenizing if one token fails. Defaults to `true`. | +| `DownloadUrl` | `bool` | Return a pre-signed download URL for file-type tokens instead of inline data. | +| `CustomHeaders` | `map[CustomHeaderKey]string` | Request-level custom headers for this call. | + Notes: -- `RedactionType` defaults to `RedactionType.PLAIN_TEXT`. +- `RedactionType` is set per token on `DetokenizeData`, not on the request. - `ContinueOnError` defaults to `true`. > [!TIP] @@ -572,15 +595,15 @@ import ( */ func main() { // Initialize Skyflow client - // Step 1: Initialize a list of tokens to be detokenized (replace with actual token values) - tokens := []string{"9738-1683-0486-1480", "6184-6357-8409-6668", "4914-9088-2814-3840"} // Replace with actual token values. - ctx := context.TODO() // Create a context for the detokenization operation. - // Step 2: Create the DetokenizeRequest object with the tokens and redaction type. + // Step 1: Create the DetokenizeRequest with tokens and per-token redaction types. detokenizeRequest := common.DetokenizeRequest{ - ReturnTokens: tokens, // List of tokens to detokenize. - RedactionType: common.PLAIN_TEXT, // Specify the redaction type (e.g., PLAIN_TEXT). + DetokenizeData: []common.DetokenizeData{ + {Token: "9738-1683-0486-1480", RedactionType: common.PLAIN_TEXT}, + {Token: "6184-6357-8409-6668", RedactionType: common.PLAIN_TEXT}, + {Token: "4914-9088-2814-3840", RedactionType: common.PLAIN_TEXT}, + }, } // Step 3: Obtain a Vault service instance for performing operations. service, serviceError := skyflowClient.Vault("9f27764a10f7946fe56b3258e117") // Replace "9f27764a10f7946fe56b3258e117" with your actual Skyflow vault ID @@ -649,13 +672,13 @@ import ( */ func main() { // Initialize Skyflow client - // Step 1: Initialize a list of tokens to be detokenized (replace with actual token values) - tokens := []string{"9738-1683-0486-1480", "6184-6357-8409-6668", "4914-9088-2814-3840"} // Replace with actual token values. - - // Step 2: Create the DetokenizeRequest and DetokenizeOptions object with the tokens and redaction type + // Step 1: Create the DetokenizeRequest with tokens and per-token redaction types request := common.DetokenizeRequest{ - Tokens: tokens, // Provide the list of tokens to detokenize - RedactionType: common.PLAIN_TEXT, // Specify the format for the detokenized data (plain text) + DetokenizeData: []common.DetokenizeData{ + {Token: "9738-1683-0486-1480", RedactionType: common.PLAIN_TEXT}, + {Token: "6184-6357-8409-6668", RedactionType: common.PLAIN_TEXT}, + {Token: "4914-9088-2814-3840", RedactionType: common.PLAIN_TEXT}, + }, } options := common.DetokenizeOptions{ ContinueOnError: false, // Continue even if one token cannot be detokenized. @@ -897,16 +920,15 @@ func main() { fmt.Println("Response for tokenized records:", resWithTokens.Data) } - // Step 4: Create a GetRequest to retrieve records based on specific column values - columnValues := []string{"", ""} // Replace with the actual column value - getByColumnRequest := common.GetRequest{ - Table: "", // Replace with the actual table name - ColumnName: "", // Replace with the actual column name - ColumnValues: columnValues, // Add the list of column values - } - // Send the request to the Skyflow vault and retrieve the records filtered by column values - getByColumnResponse, getErrByColumn := service.Get(ctx, getByColumnRequest, common.GetOptions{ - RedactionType: common.PLAIN_TEXT, // Redact data as plain text + // Step 4: Retrieve records based on specific column values + // ColumnName and ColumnValues belong on GetOptions, not GetRequest + columnValues := []string{"", ""} + getByColumnResponse, getErrByColumn := service.Get(ctx, common.GetRequest{ + Table: "", + }, common.GetOptions{ + ColumnName: "", // Column to filter by (must be unique in schema) + ColumnValues: columnValues, // Values to match in that column + RedactionType: common.PLAIN_TEXT, }) if getErrByColumn != nil { // Handle any errors during the retrieval process @@ -1108,18 +1130,14 @@ func main() { columnValues := []string{"john.doe@gmail.com", "jane.doe@gmail.com"} // Replace with actual values // Step 2: Create a GetRequest and GetOptions to retrieve records based on column values - // The request specifies: - // - `table`: The table from which the records will be retrieved - // - `columnName`: The column to filter the records by (e.g., "email") - // - `columnValues`: The list of values to match in the specified column - // - `redactionType`: Defines how sensitive data should be redacted (set to PLAIN_TEXT here) + // ColumnName and ColumnValues are set on GetOptions, not GetRequest request := common.GetRequest{ - Table: "table1", // Replace with the actual table name - ColumnName: "email", // The column to filter by (e.g., "email") - ColumnValues: columnValues, // The list of column values to match + Table: "table1", // Replace with the actual table name } options := common.GetOptions{ - RedactionType: common.PLAIN_TEXT, // Set the redaction type (e.g., PLAIN_TEXT) + ColumnName: "email", // The column to filter by (must be unique in schema) + ColumnValues: columnValues, // The list of column values to match + RedactionType: common.PLAIN_TEXT, } // Set up the Skyflow vault service @@ -1160,6 +1178,21 @@ Sample response: "Errors": [] } ``` +#### `GetOptions` fields + +| Field | Type | Description | +|-------|------|-------------| +| `RedactionType` | `RedactionType` | How to display sensitive data (`PLAIN_TEXT`, `MASKED`, `REDACTED`, `DEFAULT`). | +| `ReturnTokens` | `bool` | Return tokens instead of plain-text values. | +| `ColumnName` | `string` | Filter by this column (must be unique in schema). Use with `ColumnValues`. | +| `ColumnValues` | `[]string` | Values to match in `ColumnName`. Cannot be combined with `Ids`. | +| `Fields` | `[]string` | Return only these specific fields. | +| `Offset` | `string` | Pagination offset. | +| `Limit` | `string` | Pagination limit. | +| `OrderBy` | `OrderByEnum` | Sort order: `ASCENDING`, `DESCENDING`, or `NONE`. | +| `DownloadUrl` | `bool` | Return a pre-signed download URL for file-type columns. | +| `CustomHeaders` | `map[CustomHeaderKey]string` | Request-level custom headers for this call. | + #### Redaction types Redaction types determine how sensitive data is displayed when retrieved from the vault. @@ -1194,27 +1227,24 @@ import ( */ func main() { // Initialize Skyflow client - // Step 1: Prepare the data to update in the vault - // Use a map to store the data that will be updated in the specified table + // Step 1: Prepare the data to update in the vault — include SkyflowId as a key in the map data := map[string]interface{}{ - "SkyflowId": "", // Skyflow ID for identifying the record to update - "": "", // Example of a column name and its value to update - "": "", // Another example of a column name and its value to update - } - // Step 2: Prepare the tokens (if necessary) for certain columns that require tokenization - // Use a map to specify columns that need tokens in the update request - tokens := map[string]interface{}{ - "COLUMN_NAME_2": "", - } + "SkyflowId": "", // Skyflow ID for identifying the record to update + "": "", // Column name and new value + "": "", // Column name and new value + } + // Step 2: Optionally provide BYOT tokens for specific columns + tokens := map[string]interface{}{ + "": "", + } // Define the context for the API call ctx := context.TODO() // Using context to manage the API request lifecycle // Step 3: Create an UpdateRequest to specify the update operation - // The request includes the table name, token mode, data, tokens, and the returnTokens flag updateRequest := common.UpdateRequest{ - Table: "", // Replace with the actual table name - Id: "", // The Skyflow ID to identify the record to update - Values: data, // The data to update in the record + Table: "", // Replace with the actual table name + Data: data, // The data to update; SkyflowId identifies the record + Tokens: tokens, // Optional: BYOT tokens for specific columns } updateOptions := common.UpdateOptions{ ReturnTokens: true, // Specify whether to return tokens in the response @@ -1262,30 +1292,27 @@ import ( func main() { // Initialize Skyflow client - // Step 1: Prepare the data to update in the vault - // Use a map to store the data that will be updated in the specified table + // Step 1: Prepare the data to update in the vault — include SkyflowId as a key in the map data := map[string]interface{}{ - "SkyflowId": "5b699e2c-4301-4f9f-bcff-0a8fd3057413", // Skyflow ID identifies the record to update - "name": "john doe", // Updating the "name" column with a new value - "card_number": "4111111111111115", // Updating the "card_number" column with a new value + "SkyflowId": "5b699e2c-4301-4f9f-bcff-0a8fd3057413", // Skyflow ID identifies the record to update + "name": "john doe", // New value for the "name" column + "card_number": "4111111111111115", // New value for the "card_number" column } - // Step 2: Prepare the tokens to include in the update request - // Tokens can be included to update sensitive data with tokenized values + // Step 2: Optionally provide BYOT tokens for specific columns tokens := map[string]interface{}{ "name": "72b8ffe3-c8d3-4b4f-8052-38b2a7405b5a", } // Step 3: Create an UpdateRequest to define the update operation - // The request specifies the table name, token mode, data, and tokens for the update updateRequest := common.UpdateRequest{ Table: "table1", // Replace with the actual table name - Id: "5b699e2c-4301-4f9f-bcff-0a8fd3057413", // Skyflow ID to identify the record to update - Values: data, // The data to update in the record + Data: data, // The data to update; SkyflowId identifies the record + Tokens: tokens, // Optional: BYOT tokens for specific columns } // Define update options, including tokenization mode updateOptions := common.UpdateOptions{ - ReturnTokens: true, // Specify whether to return tokens in the response - TokenMode: common.DISABLE, // Specify tokenization mode (e.g., DISABLE means no tokenization) + ReturnTokens: true, // Specify whether to return tokens in the response + TokenMode: common.DISABLE, // Specify tokenization mode (e.g., DISABLE means no tokenization) } @@ -1738,7 +1765,7 @@ customHeaders := map[common.CustomHeaderKey]string{ } skyflowClient, err := client.NewSkyflow( - client.WithVaultConfig(vaultConfig), + client.WithVaults(vaultConfig), client.WithCredentials(skyflowCredentials), client.WithCustomHeaders(customHeaders), ) @@ -2299,6 +2326,20 @@ Sample Response: - Presentations: `ppt`, `pptx` - Audio: `mp3`, `wav` +**`MaskingMethod` values (image files):** + +| Value | Description | +|-------|-------------| +| `common.BLACKBOX` | Cover detected entities with a solid black rectangle. | +| `common.BLUR` | Apply a gaussian blur over detected entities. | + +**`OutputTranscription` values (audio files):** + +| Value | Description | +|-------|-------------| +| `common.PLAINTEXT_TRANSCRIPTION` | Return transcript as plain text. | +| `common.DIARIZED_TRANSCRIPTION` | Return transcript with speaker labels. | + **Note:** - Transformations cannot be applied to Documents, Images, or PDFs file formats. - The `waitTime` option must be ≤ 64 seconds; otherwise, an error is thrown. @@ -2607,6 +2648,97 @@ Sample response: ``` +## Client management + +After the Skyflow client is initialized, you can add, update, retrieve, and remove vault and connection configurations at runtime without recreating the client. + +### Vault management + +| Method | Description | +|--------|-------------| +| `AddVaultConfig(config VaultConfig)` | Add a new vault after initialization | +| `RemoveVaultConfig(vaultId string)` | Remove a vault by ID | +| `UpdateVaultConfig(config VaultConfig)` | Update an existing vault configuration | +| `GetVaultConfig(vaultId string)` | Retrieve a vault configuration by ID | + +```go +import ( + "fmt" + "github.com/skyflowapi/skyflow-go/v2/utils/common" +) + +// Add a new vault +newVault := common.VaultConfig{ + VaultId: "", + ClusterId: "", + Env: common.PROD, + Credentials: common.Credentials{Token: ""}, +} +if err := skyflowClient.AddVaultConfig(newVault); err != nil { + fmt.Println("Error adding vault:", err) +} + +// Retrieve vault configuration +vaultCfg, err := skyflowClient.GetVaultConfig("") +if err != nil { + fmt.Println("Error getting vault config:", err) +} else { + fmt.Println("Vault config:", vaultCfg) +} + +// Update an existing vault configuration +updatedVault := common.VaultConfig{ + VaultId: "", + ClusterId: "", + Env: common.PROD, +} +if err := skyflowClient.UpdateVaultConfig(updatedVault); err != nil { + fmt.Println("Error updating vault:", err) +} + +// Remove a vault +if err := skyflowClient.RemoveVaultConfig(""); err != nil { + fmt.Println("Error removing vault:", err) +} +``` + +### Connection management + +| Method | Description | +|--------|-------------| +| `AddConnectionConfig(config ConnectionConfig)` | Add a new connection after initialization | +| `RemoveConnectionConfig(connId string)` | Remove a connection by ID | +| `UpdateConnectionConfig(config ConnectionConfig)` | Update an existing connection configuration | +| `GetConnectionConfig(connId string)` | Retrieve a connection configuration by ID | + +### Credential management + +| Method | Description | +|--------|-------------| +| `AddSkyflowCredentials(config Credentials)` | Add client-level credentials | +| `UpdateSkyflowCredentials(credentials Credentials)` | Update client-level credentials | +| `GetSkyflowCredentials()` | Get current client-level credentials | + +### Log level management + +| Method | Description | +|--------|-------------| +| `UpdateLogLevel(logLevel LogLevel)` | Update the log level at runtime | +| `GetLoglevel()` | Get the current log level | + +```go +import "github.com/skyflowapi/skyflow-go/v2/utils/logger" + +// Change log level at runtime +skyflowClient.UpdateLogLevel(logger.INFO) + +// Get current log level +level := skyflowClient.GetLoglevel() +fmt.Println("Current log level:", *level) +``` + +--- + ## Authentication & authorization ### Types of credentials @@ -3113,7 +3245,20 @@ func main() { ### Catching SkyflowError instances -All SDK methods return `*skyflowError.SkyflowError` as the error type, so you can call its methods directly without a type assertion. Check for `nil` before accessing the error fields. +All SDK methods return `*skyflowError.SkyflowError` as the error type. Check for `nil` before accessing the error fields. + +**`SkyflowError` methods:** + +| Method | Return type | Description | +|--------|-------------|-------------| +| `GetMessage()` | `string` | Human-readable error message. | +| `GetHttpStatusCode()` | `string` | HTTP status code (e.g. `"400"`, `"401"`). Preferred over `GetCode()`. | +| `GetHttpCode()` | `string` | Alias for `GetHttpStatusCode()`. | +| `GetCode()` | `string` | Error code. Deprecated — use `GetHttpStatusCode()` instead. | +| `GetRequestId()` | `string` | Request ID for tracing and support. | +| `GetGrpcCode()` | `string` | gRPC status code when applicable. | +| `GetDetails()` | `[]interface{}` | Structured error details array from the API response. | +| `GetResponseBody()` | `map[string]interface{}` | Raw response body from the API. | ```go import ( @@ -3121,15 +3266,14 @@ import ( skyflowError "github.com/skyflowapi/skyflow-go/v2/utils/error" ) -res, skyErr := service.Insert(ctx, insertRequest) -if skyErr, ok := err.(*skyflowError.SkyflowError); ok { - // Skyflow-specific error - fmt.Println("code:", skyErr.GetHttpCode()) - fmt.Println("message:", skyErr.GetMessage()) -} else { - // Generic / unexpected error - fmt.Println("unexpected error:", err) +res, err := service.Insert(ctx, insertRequest) +if err != nil { + fmt.Println("HTTP status:", err.GetHttpStatusCode()) + fmt.Println("message:", err.GetMessage()) + fmt.Println("request ID:", err.GetRequestId()) + fmt.Println("details:", err.GetDetails()) } +_ = res ``` ### Bearer token expiration edge cases diff --git a/docs/api_reference.md b/docs/api_reference.md new file mode 100644 index 00000000..d30d061f --- /dev/null +++ b/docs/api_reference.md @@ -0,0 +1,896 @@ +# API Reference + +A reference for the public Skyflow Go SDK v2 surface: client-management methods, config structs, request and response objects, helper types, enums, service-account utilities, and error handling. For task-oriented usage and examples, see the [README](../README.md). + +All types, fields, and enum values below are taken directly from the SDK source. + +## Table of Contents + +- [Client management methods](#client-management-methods) +- [Config classes](#config-classes) +- [Request objects](#request-objects) +- [Response objects](#response-objects) +- [Helper classes](#helper-classes) +- [Enums](#enums) +- [Service account utilities](#service-account-utilities) +- [Error handling](#error-handling) + +--- + +## Client management methods + +### Constructor + +| Function | Returns | Description | +|----------|---------|-------------| +| `NewSkyflow(opts ...Option)` | `(*Skyflow, *SkyflowError)` | Build and return a configured Skyflow client. | + +### Option functions + +Pass `Option` values to `NewSkyflow` to configure the client. + +| Function | Description | +|----------|-------------| +| `WithVaults(config ...VaultConfig) Option` | Add one or more vault configurations. | +| `WithConnections(config ...ConnectionConfig) Option` | Add one or more connection configurations. | +| `WithCredentials(credentials Credentials) Option` | Set client-level credentials applied when a vault or connection config does not specify its own. | +| `WithLogLevel(logLevel LogLevel) Option` | Set the initial log level. See [`LogLevel`](#loglevel). | +| `WithCustomHeaders(headers map[CustomHeaderKey]string) Option` | Set client-level custom headers sent with every request. See [`CustomHeaderKey`](#customheaderkey). | + +```go +import ( + "github.com/skyflowapi/skyflow-go/v2/client" + "github.com/skyflowapi/skyflow-go/v2/utils/common" + "github.com/skyflowapi/skyflow-go/v2/utils/logger" +) + +skyflowClient, err := client.NewSkyflow( + client.WithVaults(common.VaultConfig{ + VaultId: "", + ClusterId: "", + Env: common.PROD, + Credentials: common.Credentials{ + ApiKey: "", + }, + }), + client.WithLogLevel(logger.ERROR), +) +``` + +### Controller accessors + +| Method | Returns | Description | +|--------|---------|-------------| +| `Vault(vaultID ...string)` | `(*VaultService, *SkyflowError)` | Get the vault service. Uses the first configured vault if no ID is given. | +| `Connection(connectionId ...string)` | `(*ConnectionService, *SkyflowError)` | Get the connection service. Uses the first configured connection if no ID is given. | +| `Detect(vaultID ...string)` | `(*DetectService, *SkyflowError)` | Get the Detect service. Uses the first configured vault if no ID is given. | + +### Instance management methods + +All mutating methods return `*SkyflowError` (nil on success) unless the table notes otherwise. + +| Method | Returns | Description | +|--------|---------|-------------| +| `AddVaultConfig(VaultConfig)` | `*SkyflowError` | Add a vault after initialization. | +| `GetVaultConfig(vaultId string)` | `(*VaultConfig, *SkyflowError)` | Retrieve a vault configuration by ID. | +| `UpdateVaultConfig(VaultConfig)` | `*SkyflowError` | Replace an existing vault configuration (matched by `VaultId`). | +| `RemoveVaultConfig(vaultId string)` | `*SkyflowError` | Remove a vault configuration. | +| `AddConnectionConfig(ConnectionConfig)` | `*SkyflowError` | Add a connection after initialization. | +| `GetConnectionConfig(connId string)` | `(*ConnectionConfig, *SkyflowError)` | Retrieve a connection configuration by ID. | +| `UpdateConnectionConfig(ConnectionConfig)` | `*SkyflowError` | Replace an existing connection configuration. | +| `RemoveConnectionConfig(connectionId string)` | `*SkyflowError` | Remove a connection configuration. | +| `AddSkyflowCredentials(Credentials)` | `*SkyflowError` | Set client-level credentials. | +| `UpdateSkyflowCredentials(Credentials)` | `*SkyflowError` | Replace client-level credentials. | +| `GetSkyflowCredentials()` | `*Credentials` | Get the current client-level credentials. | +| `GetLoglevel()` | `*LogLevel` | Get the current log level. | +| `UpdateLogLevel(LogLevel)` | — | Change the log level at runtime. | + +```go +// Manage configuration after the client is built +skyflowClient.AddVaultConfig(common.VaultConfig{ + VaultId: "", + ClusterId: "", + Credentials: common.Credentials{ApiKey: ""}, +}) +skyflowClient.UpdateLogLevel(logger.DEBUG) +level := skyflowClient.GetLoglevel() +``` + +--- + +## Config classes + +### `VaultConfig` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — passed to `WithVaults()`, `AddVaultConfig()`, and `UpdateVaultConfig()`. + +| Field | Type | Description | +|-------|------|-------------| +| `VaultId` | `string` | _(required)_ Vault ID. | +| `ClusterId` | `string` | _(required)_ Cluster ID — the first segment of the vault URL. | +| `Env` | `Env` | Deployment environment. Default: `PROD`. See [`Env`](#env). | +| `Credentials` | `Credentials` | Vault-specific credentials. Overrides client-level credentials for this vault. | +| `BaseVaultUrl` | `string` | _(optional)_ Override the base vault URL. | + +### `ConnectionConfig` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — passed to `WithConnections()`, `AddConnectionConfig()`, and `UpdateConnectionConfig()`. + +| Field | Type | Description | +|-------|------|-------------| +| `ConnectionId` | `string` | _(required)_ Connection ID. | +| `ConnectionUrl` | `string` | _(required)_ Connection URL. | +| `Credentials` | `Credentials` | Connection-specific credentials. Overrides client-level credentials for this connection. | + +### `Credentials` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — use exactly one authentication field; the others should be left empty. + +| Field | Type | Description | +|-------|------|-------------| +| `ApiKey` | `string` | API key for direct authentication. | +| `Token` | `string` | Static bearer token. | +| `Path` | `string` | Path to a service account `credentials.json` file. | +| `CredentialsString` | `string` | Service account credentials as a JSON string. | +| `Roles` | `[]string` | _(optional)_ Role IDs to scope the generated bearer token. | +| `Context` | `interface{}` | _(optional)_ Context value embedded in the bearer token for context-aware authorization. | + +--- + +## Request objects + +### Vault API + +#### `InsertRequest` + +Passed to `vault.Insert()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Table` | `string` | _(required)_ | Target table name. | +| `Values` | `[]map[string]interface{}` | _(required)_ | List of records to insert. Each map is a `column → value` mapping. | + +#### `InsertOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `ReturnTokens` | `bool` | `false` | Return tokens for the inserted values. | +| `Upsert` | `string` | `""` | Column name to use as the upsert key (column must have a `unique` constraint). | +| `Homogeneous` | `bool` | `false` | Treat the batch as homogeneous (all records share the same columns). | +| `TokenMode` | `BYOT` | `DISABLE` | Bring-your-own-token mode. See [`BYOT`](#byot). | +| `ContinueOnError` | `bool` | `false` | Continue the batch despite partial per-record errors. | +| `Tokens` | `[]map[string]interface{}` | `nil` | BYOT token values aligned positionally with `Values` (used with `TokenMode`). | +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. See [`CustomHeaderKey`](#customheaderkey). | + +--- + +#### `DetokenizeRequest` + +Passed to `vault.Detokenize()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `DetokenizeData` | `[]DetokenizeData` | _(required)_ | List of token-redaction pairs to detokenize. See [`DetokenizeData`](#detokenizedata). | + +#### `DetokenizeOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `ContinueOnError` | `bool` | `false` | Continue despite per-token errors. | +| `DownloadUrl` | `bool` | `false` | Return file download URLs for file-type tokens. | +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +#### `GetRequest` + +Passed to `vault.Get()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Table` | `string` | _(required)_ | Target table name. | +| `Ids` | `[]string` | `nil` | Skyflow IDs to retrieve. Mutually exclusive with `ColumnName`/`ColumnValues` in `GetOptions`. | + +#### `GetOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `RedactionType` | `RedactionType` | `DEFAULT` | Redaction applied to returned values. See [`RedactionType`](#redactiontype). | +| `ReturnTokens` | `bool` | `false` | Return tokens instead of plain values. | +| `Fields` | `[]string` | `nil` | Specific columns to return. Returns all columns if empty. | +| `Offset` | `string` | `""` | Pagination offset. | +| `Limit` | `string` | `""` | Pagination limit. | +| `DownloadUrl` | `bool` | `false` | Return file download URLs for file columns. | +| `ColumnName` | `string` | `""` | Unique column to look up by value. Mutually exclusive with `Ids`. | +| `ColumnValues` | `[]string` | `nil` | Values for `ColumnName`. | +| `OrderBy` | `OrderByEnum` | `NONE` | Sort order. See [`OrderByEnum`](#orderbyenum). | +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +#### `UpdateRequest` + +Passed to `vault.Update()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Table` | `string` | _(required)_ | Target table name. | +| `Data` | `map[string]interface{}` | _(required)_ | Map containing `"SkyflowId"` (the record to update) plus the columns and their new values. | +| `Tokens` | `map[string]interface{}` | `nil` | BYOT token values for the updated columns. | + +#### `UpdateOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `ReturnTokens` | `bool` | `false` | Return tokens for the updated record. | +| `TokenMode` | `BYOT` | `DISABLE` | Bring-your-own-token mode. See [`BYOT`](#byot). | +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +#### `DeleteRequest` + +Passed to `vault.Delete()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Table` | `string` | _(required)_ | Target table name. | +| `Ids` | `[]string` | _(required)_ | Skyflow IDs of the records to delete. | + +#### `DeleteOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +#### `QueryRequest` + +Passed to `vault.Query()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Query` | `string` | _(required)_ | SQL-like query string to execute against the vault. | + +#### `QueryOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +#### `TokenizeRequest` + +Each element in the `[]TokenizeRequest` slice passed to `vault.Tokenize()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Value` | `string` | _(required)_ | The value to tokenize. | +| `ColumnGroup` | `string` | _(required)_ | The column group that defines the tokenization policy. | + +#### `TokenizeOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +#### `FileUploadRequest` + +Passed to `vault.UploadFile()`. Provide exactly one file source: `FilePath`, `Base64`, or `FileObject`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Table` | `string` | _(required)_ | Target table name. | +| `SkyflowId` | `string` | `""` | Existing record ID to attach the file to. Omit to create a new record. | +| `ColumnName` | `string` | `""` | File column name. | +| `FilePath` | `string` | `""` | Path to a local file to upload. | +| `Base64` | `string` | `""` | Base64-encoded file content. | +| `FileName` | `string` | `""` | Override the file name sent to the vault. | +| `FileObject` | `os.File` | — | A file object to upload. | + +#### `FileUploadOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +### Connection API + +#### `InvokeConnectionRequest` + +Passed to `connection.Invoke()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Method` | `RequestMethod` | `POST` | HTTP method. See [`RequestMethod`](#requestmethod). | +| `PathParams` | `map[string]string` | `nil` | Path parameter substitutions. | +| `QueryParams` | `map[string]interface{}` | `nil` | Query string parameters. | +| `Headers` | `map[string]string` | `nil` | Additional request headers. | +| `Body` | `interface{}` | `nil` | Request body. | + +--- + +### Detect API + +#### `DeidentifyTextRequest` + +Passed to `detect.DeidentifyText()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Text` | `string` | _(required)_ | Text to de-identify. | +| `Entities` | `[]DetectEntities` | `nil` | Entity types to detect. Detects all types if empty. See [`DetectEntities`](#detectentities). | +| `AllowRegexList` | `[]string` | `nil` | Regex patterns to always treat as detectable. | +| `RestrictRegexList` | `[]string` | `nil` | Regex patterns to exclude from detection. | +| `TokenFormat` | `TokenFormat` | — | Token format per entity type. See [`TokenFormat`](#tokenformat). | +| `Transformations` | `Transformations` | — | Data transformations (e.g. date shifting). See [`Transformations`](#transformations). | + +#### `DeidentifyTextOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +#### `ReidentifyTextRequest` + +Passed to `detect.ReidentifyText()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `Text` | `string` | _(required)_ | The de-identified text to re-identify. | +| `RedactedEntities` | `[]DetectEntities` | `nil` | Entity types to keep redacted in the output. | +| `MaskedEntities` | `[]DetectEntities` | `nil` | Entity types to mask in the output. | +| `PlainTextEntities` | `[]DetectEntities` | `nil` | Entity types to reveal as plain text. | + +#### `ReidentifyTextOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +#### `DeidentifyFileRequest` + +Passed to `detect.DeidentifyFile()`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `File` | `FileInput` | _(required)_ | File source. See [`FileInput`](#fileinput). | +| `Entities` | `[]DetectEntities` | `nil` | Entity types to detect. | +| `AllowRegexList` | `[]string` | `nil` | Regex patterns to always detect. | +| `RestrictRegexList` | `[]string` | `nil` | Regex patterns to exclude. | +| `TokenFormat` | `TokenFormat` | — | Token format per entity type. | +| `Transformations` | `Transformations` | — | Transformations (not supported for images/PDFs). | +| `OutputProcessedImage` | `bool` | `false` | Include the processed image in the response. | +| `OutputOcrText` | `bool` | `false` | Include OCR-extracted text in the response. | +| `MaskingMethod` | `MaskingMethod` | — | Visual masking method for images. See [`MaskingMethod`](#maskingmethod). | +| `PixelDensity` | `int` | `0` | Pixel density for PDF processing. | +| `MaxResolution` | `int` | `0` | Maximum resolution for PDF processing. | +| `OutputProcessedAudio` | `bool` | `false` | Include processed audio in the response. | +| `OutputTranscription` | `DetectOutputTranscriptions` | — | Transcription mode for audio. See [`DetectOutputTranscriptions`](#detectoutputtranscriptions). | +| `Bleep` | `AudioBleep` | — | Audio bleep configuration. See [`AudioBleep`](#audiobleep). | +| `OutputDirectory` | `string` | `""` | Directory to write the processed file. | +| `WaitTime` | `int` | `0` | Maximum seconds to wait for async file processing (≤ 64). | + +#### `DeidentifyFileOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +#### `GetDetectRunRequest` + +Passed to `detect.GetDetectRun()` to poll the status of an async `DeidentifyFile` call. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `RunId` | `string` | _(required)_ | The `RunId` returned by a prior `DeidentifyFile` response. | + +#### `GetDetectRunOptions` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `CustomHeaders` | `map[CustomHeaderKey]string` | `nil` | Per-request custom headers. | + +--- + +## Response objects + +> **The `Errors` field** is present on most responses. It is populated only on partial failure (for example when `ContinueOnError: true` is set); it is nil or empty when there are no errors. + +### `InsertResponse` + +Returned by `vault.Insert()`. + +| Field | Type | Description | +|-------|------|-------------| +| `InsertedFields` | `[]map[string]interface{}` | One entry per inserted record. Each map contains `skyflow_id`; with `ReturnTokens: true`, also a token per column; with `ContinueOnError: true`, also a `request_index`. | +| `Errors` | `[]map[string]interface{}` | Per-record errors when `ContinueOnError: true`. Each map contains `request_index`, `error`, and `http_code`. | + +### `DetokenizeResponse` + +Returned by `vault.Detokenize()`. + +| Field | Type | Description | +|-------|------|-------------| +| `DetokenizedFields` | `[]DetokenizeRecordResponse` | One entry per successfully detokenized token. See [`DetokenizeRecordResponse`](#detokenizerecordresponse). | +| `Errors` | `[]DetokenizeRecordResponse` | Per-token errors when `ContinueOnError: true`. | + +### `GetResponse` + +Returned by `vault.Get()`. + +| Field | Type | Description | +|-------|------|-------------| +| `Data` | `[]map[string]interface{}` | Retrieved records as `column → value` maps. Returns tokens when `ReturnTokens: true`. | +| `Errors` | `[]map[string]interface{}` | Errors, if any. | + +### `UpdateResponse` + +Returned by `vault.Update()`. + +| Field | Type | Description | +|-------|------|-------------| +| `UpdatedField` | `map[string]interface{}` | The updated record's `skyflow_id` and, when `ReturnTokens: true`, a token per updated column. | +| `Errors` | `[]map[string]interface{}` | Errors, if any. | + +### `DeleteResponse` + +Returned by `vault.Delete()`. + +| Field | Type | Description | +|-------|------|-------------| +| `DeletedIds` | `[]string` | Skyflow IDs of the deleted records. | +| `Errors` | `[]map[string]interface{}` | Errors, if any. | + +### `QueryResponse` + +Returned by `vault.Query()`. + +| Field | Type | Description | +|-------|------|-------------| +| `Fields` | `[]map[string]interface{}` | Matching records. Each map includes a `tokenized_data` entry. | +| `Errors` | `[]map[string]interface{}` | Always nil (errors from query throw `SkyflowError` directly). | + +### `TokenizeResponse` + +Returned by `vault.Tokenize()`. + +| Field | Type | Description | +|-------|------|-------------| +| `Tokens` | `[]string` | One token per input `TokenizeRequest`, in order. | +| `Errors` | `[]map[string]interface{}` | Errors, if any. | + +### `FileUploadResponse` + +Returned by `vault.UploadFile()`. + +| Field | Type | Description | +|-------|------|-------------| +| `SkyflowId` | `string` | Skyflow ID of the record the file was attached to (or the newly created record). | +| `Errors` | `[]map[string]interface{}` | Errors, if any. | + +### `InvokeConnectionResponse` + +Returned by `connection.Invoke()`. + +| Field | Type | Description | +|-------|------|-------------| +| `Data` | `interface{}` | The response body from the downstream service. | +| `Metadata` | `map[string]interface{}` | Response metadata (e.g. forwarded HTTP headers). | +| `Errors` | `map[string]interface{}` | Errors, if any. | + +### `DeidentifyTextResponse` + +Returned by `detect.DeidentifyText()`. + +| Field | Type | Description | +|-------|------|-------------| +| `ProcessedText` | `string` | The de-identified text with entity values replaced by tokens. | +| `Entities` | `[]EntityInfo` | Detected entities. See [`EntityInfo`](#entityinfo). | +| `WordCount` | `int` | Word count of the input text. | +| `CharCount` | `int` | Character count of the input text. | +| `Errors` | `[]map[string]interface{}` | Errors, if any. | + +### `ReidentifyTextResponse` + +Returned by `detect.ReidentifyText()`. + +| Field | Type | Description | +|-------|------|-------------| +| `ProcessedText` | `string` | The re-identified text with tokens replaced by their original values. | +| `Errors` | `[]map[string]interface{}` | Errors, if any. | + +### `DeidentifyFileResponse` + +Returned by both `detect.DeidentifyFile()` and `detect.GetDetectRun()`. + +| Field | Type | Description | +|-------|------|-------------| +| `File` | `FileInfo` | Metadata about the processed file. See [`FileInfo`](#fileinfo). | +| `FileBase64` | `string` | Base64-encoded processed file content (when `OutputProcessedImage: true`). | +| `Type` | `string` | MIME type of the output file. | +| `Extension` | `string` | File extension of the output file. | +| `WordCount` | `int` | Word count (text and document files). | +| `CharCount` | `int` | Character count (text and document files). | +| `SizeInKb` | `float64` | Output file size in kilobytes. | +| `DurationInSeconds` | `float64` | Duration in seconds (audio and video files). | +| `PageCount` | `int` | Page count (PDF files). | +| `SlideCount` | `int` | Slide count (presentation files). | +| `Entities` | `[]FileEntityInfo` | Detected entities. See [`FileEntityInfo`](#fileentityinfo). | +| `RunId` | `string` | Run ID for polling async processing with `GetDetectRun()`. | +| `Status` | `string` | Processing status. See [`DeidentifyFileStatus`](#deidentifyfilestatus). | +| `Errors` | `[]map[string]interface{}` | Errors, if any. | + +--- + +## Helper classes + +### `DetokenizeData` + +Used inside [`DetokenizeRequest`](#detokenizerequest) to pair a token with a redaction type. + +| Field | Type | Description | +|-------|------|-------------| +| `Token` | `string` | The token to detokenize. | +| `RedactionType` | `RedactionType` | Redaction applied to the returned value. See [`RedactionType`](#redactiontype). | + +### `DetokenizeRecordResponse` + +Each element returned in `DetokenizeResponse.DetokenizedFields` and `DetokenizeResponse.Errors`. + +| Field | Type | Description | +|-------|------|-------------| +| `Token` | `string` | The input token. | +| `Value` | `string` | The detokenized value. Empty on error. | +| `Type` | `string` | The value type (e.g. `"STRING"`). Empty on error. | +| `Error` | `string` | Error message. Empty on success. | +| `RequestId` | `string` | Server request ID for this token — useful for support escalations. | + +### `EntityInfo` + +Each element in `DeidentifyTextResponse.Entities`. + +| Field | Type | Description | +|-------|------|-------------| +| `Token` | `string` | The token that replaced the original entity value. | +| `Value` | `string` | The original entity value. | +| `Entity` | `string` | Entity type label (e.g. `"email_address"`). | +| `Scores` | `map[string]float64` | Confidence scores per entity type. | +| `ProcessedIndex` | `TextIndex` | Character offsets of the token in the processed text. | +| `TextIndex` | `TextIndex` | Character offsets of the entity in the original text. | + +### `TextIndex` + +Used in [`EntityInfo`](#entityinfo). + +| Field | Type | Description | +|-------|------|-------------| +| `Start` | `int` | Start character offset (inclusive). | +| `End` | `int` | End character offset (exclusive). | + +### `FileEntityInfo` + +Each element in `DeidentifyFileResponse.Entities`. + +| Field | Type | Description | +|-------|------|-------------| +| `File` | `string` | File name or identifier. | +| `Type` | `string` | Output file type. | +| `Extension` | `string` | Output file extension. | + +### `FileInfo` + +Returned in `DeidentifyFileResponse.File`. + +| Field | Type | Description | +|-------|------|-------------| +| `Name` | `string` | Original file name. | +| `Size` | `int64` | File size in bytes. | +| `Type` | `string` | MIME type. | +| `LastModified` | `int64` | Last-modified timestamp (milliseconds since Unix epoch). | + +### `FileInput` + +Used inside [`DeidentifyFileRequest`](#deidentifyfilerequest). Provide exactly one source field. + +| Field | Type | Description | +|-------|------|-------------| +| `FilePath` | `string` | Path to a local file. | +| `File` | `*os.File` | An open file handle. | + +### `AudioBleep` + +Used inside [`DeidentifyFileRequest`](#deidentifyfilerequest) to configure audio bleeping. + +| Field | Type | Description | +|-------|------|-------------| +| `Gain` | `int` | Gain level of the bleep tone. | +| `Frequency` | `int` | Frequency (Hz) of the bleep tone. | +| `StartPadding` | `float64` | Seconds of silence before the bleep. | +| `StopPadding` | `float64` | Seconds of silence after the bleep. | + +### `TokenFormat` + +Used inside [`DeidentifyTextRequest`](#deidentifytextrequest) and [`DeidentifyFileRequest`](#deidentifyfilerequest) to control the token type per entity. + +| Field | Type | Description | +|-------|------|-------------| +| `DefaultType` | `TokenTypeDefault` | Default token type for entities not explicitly listed. See [`TokenTypeDefault`](#tokentypedefault). | +| `VaultToken` | `[]DetectEntities` | Entities to tokenize as vault tokens. | +| `EntityUniqueCounter` | `[]DetectEntities` | Entities to tokenize as entity-unique-counter tokens. | +| `EntityOnly` | `[]DetectEntities` | Entities to tokenize as entity-only tokens. | + +### `Transformations` + +Used inside [`DeidentifyTextRequest`](#deidentifytextrequest) and [`DeidentifyFileRequest`](#deidentifyfilerequest). + +| Field | Type | Description | +|-------|------|-------------| +| `ShiftDates` | `DateTransformation` | Date-shifting transformation to apply. | + +### `DateTransformation` + +Used inside [`Transformations`](#transformations). + +| Field | Type | Description | +|-------|------|-------------| +| `MaxDays` | `int` | Maximum number of days to shift. | +| `MinDays` | `int` | Minimum number of days to shift. | +| `Entities` | `[]TransformationsShiftDatesEntityTypesItem` | Entity types to shift. Valid values: `Date`, `DateInterval`, `Dob`. | + +--- + +## Enums + +### `LogLevel` + +`github.com/skyflowapi/skyflow-go/v2/utils/logger` + +| Value | Description | +|-------|-------------| +| `ERROR` | Log errors only. _(default)_ | +| `INFO` | Log informational messages, warnings, and errors. | +| `DEBUG` | Log everything (DEBUG, INFO, WARN, ERROR). | +| `WARN` | Log warnings and errors. | +| `OFF` | Disable all logging. | + +### `Env` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` + +| Value | Description | +|-------|-------------| +| `PROD` | Production environment. _(default)_ | +| `STAGE` | Staging environment. | +| `SANDBOX` | Sandbox environment. | +| `DEV` | Development environment. | + +### `RedactionType` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` + +| Value | Description | +|-------|-------------| +| `PLAIN_TEXT` | Return the original, unmasked value. | +| `MASKED` | Return a partially masked value (e.g. `****1234`). | +| `REDACTED` | Return a fully redacted placeholder. | +| `DEFAULT` | Use the redaction type configured on the vault column. | + +### `BYOT` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — controls bring-your-own-token behavior for `Insert` and `Update`. + +| Value | Description | +|-------|-------------| +| `DISABLE` | Do not use BYOT tokens. _(default)_ | +| `ENABLE` | Use provided tokens where supplied; generate tokens for fields that do not supply one. | +| `ENABLE_STRICT` | All fields must supply a BYOT token; missing tokens cause an error. | + +### `RequestMethod` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — used in [`InvokeConnectionRequest`](#invokeconnectionrequest). + +| Value | Description | +|-------|-------------| +| `GET` | HTTP GET. | +| `POST` | HTTP POST. | +| `PUT` | HTTP PUT. | +| `PATCH` | HTTP PATCH. | +| `DELETE` | HTTP DELETE. | + +### `OrderByEnum` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — used in [`GetOptions`](#getoptions). + +| Value | Description | +|-------|-------------| +| `ASCENDING` | Return records in ascending order. | +| `DESCENDING` | Return records in descending order. | +| `NONE` | No specific ordering. _(default)_ | + +### `MaskingMethod` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — used in [`DeidentifyFileRequest`](#deidentifyfilerequest). + +| Value | Description | +|-------|-------------| +| `BLACKBOX` | Cover detected entities with a solid black rectangle. | +| `BLUR` | Blur detected entities with a Gaussian blur. | + +### `DetectOutputTranscriptions` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — used in [`DeidentifyFileRequest`](#deidentifyfilerequest). + +| Value | Description | +|-------|-------------| +| `PLAINTEXT_TRANSCRIPTION` | Standard plain-text transcription. | +| `DIARIZED_TRANSCRIPTION` | Transcription with speaker diarization. | +| `TRANSCRIPTION` | Basic transcription. | +| `MEDICAL_TRANSCRIPTION` | Medical-domain transcription. | +| `MEDICAL_DIARIZED_TRANSCRIPTION` | Medical transcription with speaker diarization. | + +### `DeidentifyFileStatus` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — returned in `DeidentifyFileResponse.Status`. + +| Value | Description | +|-------|-------------| +| `IN_PROGRESS` | File processing is ongoing. Poll with `GetDetectRun()`. | +| `SUCCESS` | Processing completed successfully. | +| `FAILED` | Processing failed. | + +### `TokenTypeDefault` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — used in [`TokenFormat`](#tokenformat). + +| Value | Description | +|-------|-------------| +| `TokenTypeDefaultEntityOnly` | Token represents the entity type only; no value is stored in the vault. | +| `TokenTypeDefaultEntityUnqCounter` | Deterministic token unique to the entity value (consistent across occurrences). | +| `TokenTypeDefaultVaultToken` | Token stored in the vault and associated with a `skyflow_id`. | + +### `CustomHeaderKey` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — keys for custom header maps. + +| Value | Wire header | Description | +|-------|-------------|-------------| +| `SkyflowAccountId` | `x-skyflow-account-id` | Skyflow account ID header. | +| `SkyflowAccountName` | `x-skyflow-account-name` | Skyflow account name header. | +| `RequestIdHeader` | `x-request-id` | Custom request ID for tracing. | + +### `DetectEntities` + +`github.com/skyflowapi/skyflow-go/v2/utils/common` — entity types for Detect operations. Use `All` to detect all supported types. + +| Category | Values | +|----------|--------| +| Personal identity | `Name`, `NameGiven`, `NameFamily`, `NameMedicalProfessional`, `Dob`, `Age`, `Gender`, `MaritalStatus`, `Sexuality`, `Religion`, `PoliticalAffiliation`, `PhysicalAttribute`, `Origin` | +| Contact | `EmailAddress`, `PhoneNumber`, `Location`, `LocationAddress`, `LocationAddressStreet`, `LocationCity`, `LocationState`, `LocationCountry`, `LocationZip`, `LocationCoordinate` | +| Financial | `CreditCard`, `CreditCardExpiration`, `Cvv`, `BankAccount`, `AccountNumber`, `RoutingNumber`, `Money`, `FinancialMetric`, `CorporateAction` | +| Government ID | `Ssn`, `DriverLicense`, `PassportNumber`, `HealthcareNumber`, `OrganizationId`, `NumericalPii` | +| Medical | `BloodType`, `Condition`, `Drug`, `Dose`, `Effect`, `Injury`, `MedicalCode`, `MedicalProcess`, `OrganizationMedicalFacility` | +| Date & time | `Date`, `Day`, `Month`, `Year`, `Time`, `Duration`, `DateInterval`, `Event` | +| Technology | `IpAddress`, `Url`, `Username`, `Password`, `Filename`, `VehicleId` | +| Organization | `Organization`, `Occupation`, `Project`, `Product` | +| Other | `Language`, `Statistics`, `Trend`, `ZodiacSign`, `All` | + +--- + +## Service account utilities + +`github.com/skyflowapi/skyflow-go/v2/serviceaccount` + +These functions generate bearer tokens and signed data tokens from Skyflow service account credentials. Bearer tokens are valid for 60 minutes. + +### Functions + +| Function | Parameters | Returns | Description | +|----------|------------|---------|-------------| +| `GenerateBearerToken(credentialsFilePath string, options BearerTokenOptions)` | path to `credentials.json` | `(*TokenResponse, *SkyflowError)` | Generate a bearer token from a credentials file. | +| `GenerateBearerTokenFromCreds(credentials string, options BearerTokenOptions)` | credentials JSON string | `(*TokenResponse, *SkyflowError)` | Generate a bearer token from a credentials JSON string. | +| `GenerateSignedDataTokens(credentialsFilePath string, options SignedDataTokensOptions)` | path to `credentials.json` | `([]SignedDataTokensResponse, *SkyflowError)` | Sign data tokens using a credentials file. | +| `GenerateSignedDataTokensFromCreds(credentials string, options SignedDataTokensOptions)` | credentials JSON string | `([]SignedDataTokensResponse, *SkyflowError)` | Sign data tokens using a credentials JSON string. | +| `IsExpired(tokenString string)` | — | `bool` | Returns `true` if the token is nil or has expired. Check before every API call. | + +### `BearerTokenOptions` + +| Field | Type | Description | +|-------|------|-------------| +| `Ctx` | `interface{}` | Context value embedded in the token for context-aware authorization. | +| `RoleIds` | `[]string` | Role IDs to scope the generated token. | +| `LogLevel` | `LogLevel` | Log level for this call. | + +### `SignedDataTokensOptions` + +| Field | Type | Description | +|-------|------|-------------| +| `DataTokens` | `[]string` | Data tokens to sign. | +| `TimeToLive` | `int` | Token validity in seconds. Default: `60`. | +| `Ctx` | `interface{}` | Context value embedded in the signed token. | +| `LogLevel` | `LogLevel` | Log level for this call. | + +### `TokenResponse` + +Returned by `GenerateBearerToken` and `GenerateBearerTokenFromCreds`. + +| Field | Type | Description | +|-------|------|-------------| +| `AccessToken` | `string` | The bearer token string. Pass as `Authorization: Bearer ` or in `Credentials.Token`. | +| `TokenType` | `string` | Token type (always `"Bearer"`). | + +### `SignedDataTokensResponse` + +Each element returned by `GenerateSignedDataTokens` and `GenerateSignedDataTokensFromCreds`. + +| Field | Type | Description | +|-------|------|-------------| +| `Token` | `string` | The original data token. | +| `SignedToken` | `string` | The signed token string (JWT). Use this for detokenization requests. | + +```go +import "github.com/skyflowapi/skyflow-go/v2/serviceaccount" +import "github.com/skyflowapi/skyflow-go/v2/utils/common" +import "github.com/skyflowapi/skyflow-go/v2/utils/logger" + +var token string + +func getToken() (string, error) { + if serviceaccount.IsExpired(token) { + resp, err := serviceaccount.GenerateBearerToken("", common.BearerTokenOptions{ + LogLevel: logger.ERROR, + }) + if err != nil { + return "", err + } + token = resp.AccessToken + } + return token, nil +} +``` + +--- + +## Error handling + +### `SkyflowError` + +All SDK operations return `*SkyflowError` instead of Go's built-in `error`. It is `nil` on success. + +`github.com/skyflowapi/skyflow-go/v2/utils/error` + +| Method | Return type | Description | +|--------|-------------|-------------| +| `Error() string` | `string` | Implements the `error` interface; returns the error message. | +| `GetMessage() string` | `string` | Human-readable error message. | +| `GetHttpStatusCode() string` | `string` | HTTP status code. Preferred over `GetCode()`. | +| `GetHttpCode() string` | `string` | HTTP status code string. | +| `GetCode() string` | `string` | _(deprecated)_ Use `GetHttpStatusCode()`. | +| `GetRequestId() string` | `string` | Server request ID — include in support escalations. | +| `GetGrpcCode() string` | `string` | gRPC status code (where applicable). | +| `GetDetails() []interface{}` | `[]interface{}` | Structured error detail objects. | +| `GetResponseBody() map[string]interface{}` | `map[string]interface{}` | Raw response body as a map. | + +```go +resp, skyflowErr := vault.Insert(ctx, insertRequest, insertOptions) +if skyflowErr != nil { + fmt.Println("Error message: ", skyflowErr.GetMessage()) + fmt.Println("HTTP status: ", skyflowErr.GetHttpStatusCode()) + fmt.Println("Request ID: ", skyflowErr.GetRequestId()) + fmt.Println("Details: ", skyflowErr.GetDetails()) + return +} +fmt.Println("Inserted fields:", resp.InsertedFields) +``` diff --git a/samples/v2/serviceaccount/signed_token_generation.go b/samples/v2/serviceaccount/signed_token_generation.go index cda7b55d..2310ed49 100644 --- a/samples/v2/serviceaccount/signed_token_generation.go +++ b/samples/v2/serviceaccount/signed_token_generation.go @@ -14,7 +14,8 @@ import ( /** * Example program to generate a Signed Token * The token can be generated in two ways: - * Using the file path to a credentials.json file. + * 1. Using the file path to a credentials.json file. + * 2. Using the JSON content of the credentials file as a string. */ func SignedDataTokenGenerationSample() { @@ -35,15 +36,16 @@ func SignedDataTokenGenerationSample() { } // signed data token generation using cred string + var credString = "" var tokens2 []string tokens2 = append(tokens2, "") - res2, err1 := serviceaccount.GenerateSignedDataTokensFromCreds(filePath, common.SignedDataTokensOptions{ + res2, err1 := serviceaccount.GenerateSignedDataTokensFromCreds(credString, common.SignedDataTokensOptions{ DataTokens: tokens2, - TimeToLive: 0, + TimeToLive: 60, // in seconds LogLevel: logger.ERROR, }) if err1 != nil { - fmt.Println("ERROR: ", err) + fmt.Println("ERROR: ", err1) } else { fmt.Println("RESPONSE:", res2) }