For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DocsAPI Reference
  • Fundamentals
    • Home
    • Why Skyflow?
    • Get started with Skyflow
    • Explore what Skyflow can do
    • Authenticate
    • Accounts and environments
    • Deployment models
    • Security best practices
    • Compliance and certifications
    • Get data into Skyflow
    • Platform FAQs
  • Governance
    • Overview
  • Tokenization
    • Overview
  • Connections
    • Overview
  • Processing
  • AI and data sanitization
    • Overview
  • SDKs
    • Overview
      • Go: Migrate from V1 to V2
      • Python: Migrate from V1 to V2
      • Node.js: Migrate from V1 to V2
      • Java: Migrate from V1 to V2
  • Elements
    • Collect and reveal data with Skyflow Elements
LogoLogo
Login
Login
On this page
  • Authentication
  • Initialize the client
  • Insert records
  • Other operations at a glance
  • Request options
  • Error handling
  • v2.1+ updates
  • Get help
SDKsOverview

Java SDK: Migrate from V1 to V2

Was this page helpful?
Previous

Collect and reveal data with Skyflow Elements

Next
Built with

Skyflow Java SDK v2 introduces a new authentication model, multi-vault support via a builder pattern, native Java collections in place of third-party JSON objects, and richer error diagnostics. This guide walks through the key changes with before-and-after code examples, focuses on Insert end-to-end, then shows how the same pattern applies to other operations. A final section covers the v2.1+ field and method renames, which are backward compatible.

Authentication

V1 required implementing a TokenProvider interface. V2 lets you choose from five credential types.

V1:

1static class DemoTokenProvider implements TokenProvider {
2 @Override
3 public String getBearerToken() throws Exception {
4 ResponseToken res = null;
5 try {
6 String filePath = "<YOUR_CREDENTIALS_FILE_HERE>";
7 res = Token.generateBearerToken(filePath);
8 } catch (SkyflowException e) {
9 e.printStackTrace();
10 }
11 return res.getAccessToken();
12 }
13}

V2:

1// Option 1: API key (recommended)
2Credentials skyflowCredentials = new Credentials();
3skyflowCredentials.setApiKey("<YOUR_API_KEY>");
4
5// Option 2: Environment variable — set SKYFLOW_CREDENTIALS in your environment
6
7// Option 3: Credentials file
8skyflowCredentials.setPath("<YOUR_CREDENTIALS_FILE_PATH>");
9
10// Option 4: Stringified JSON
11skyflowCredentials.setCredentialsString("<YOUR_CREDENTIALS_STRING>");
12
13// Option 5: Bearer token
14skyflowCredentials.setToken("<BEARER_TOKEN>");

Use only one authentication method per credentials object.

Initialize the client

V2 introduces a builder pattern and multi-vault support. Log levels are now per-instance instead of global.

V1:

1DemoTokenProvider demoTokenProvider = new DemoTokenProvider();
2SkyflowConfiguration skyflowConfig = new SkyflowConfiguration(
3 "<VAULT_ID>",
4 "<VAULT_URL>",
5 demoTokenProvider
6);
7Skyflow skyflowClient = Skyflow.init(skyflowConfig);

V2 (single vault):

1Credentials credentials = new Credentials();
2credentials.setPath("<YOUR_CREDENTIALS_FILE_PATH>");
3
4VaultConfig config = new VaultConfig();
5config.setVaultId("<YOUR_VAULT_ID>");
6config.setClusterId("<YOUR_CLUSTER_ID>"); // ID from your vault URL, e.g., https://{clusterId}.vault.skyflowapis.com
7config.setEnv(Env.PROD);
8config.setCredentials(credentials);
9
10Credentials skyflowCredentials = new Credentials();
11skyflowCredentials.setPath("<FALLBACK_CREDENTIALS_FILE_PATH>");
12
13Skyflow skyflowClient = Skyflow.builder()
14 .setLogLevel(LogLevel.INFO)
15 .addVaultConfig(config)
16 .addSkyflowCredentials(skyflowCredentials) // Used as a fallback if no per-vault credentials are set
17 .build();

V2 (multiple vaults):

1VaultConfig primary = new VaultConfig();
2primary.setVaultId("<PRIMARY_VAULT_ID>");
3primary.setClusterId("<PRIMARY_CLUSTER_ID>");
4primary.setEnv(Env.PROD);
5primary.setCredentials(primaryCredentials);
6
7VaultConfig secondary = new VaultConfig();
8secondary.setVaultId("<SECONDARY_VAULT_ID>");
9secondary.setClusterId("<SECONDARY_CLUSTER_ID>");
10secondary.setEnv(Env.PROD);
11secondary.setCredentials(secondaryCredentials);
12
13Skyflow skyflowClient = Skyflow.builder()
14 .setLogLevel(LogLevel.INFO)
15 .addVaultConfig(primary)
16 .addVaultConfig(secondary)
17 .build();

Key changes:

  • vaultUrl is replaced by clusterId (derived from your vault URL).
  • env is now required. Supported values: Env.PROD, Env.SANDBOX, Env.DEV.
  • Log level is set per client instance.
  • A single client can manage multiple vault configurations.

Insert records

V2 replaces JSONObject/JSONArray from third-party libraries with native HashMap and ArrayList. Requests use a builder pattern.

V1:

1JSONObject recordsJson = new JSONObject();
2JSONArray recordsArrayJson = new JSONArray();
3
4JSONObject recordJson = new JSONObject();
5recordJson.put("table", "cards");
6
7JSONObject fieldsJson = new JSONObject();
8fieldsJson.put("cardNumber", "41111111111");
9fieldsJson.put("cvv", "123");
10
11recordJson.put("fields", fieldsJson);
12recordsArrayJson.add(recordJson);
13recordsJson.put("records", recordsArrayJson);
14
15JSONObject insertResponse = skyflowClient.insert(recordsJson);

V2:

1ArrayList<HashMap<String, Object>> values = new ArrayList<>();
2HashMap<String, Object> value = new HashMap<>();
3value.put("<COLUMN_NAME_1>", "<COLUMN_VALUE_1>");
4value.put("<COLUMN_NAME_2>", "<COLUMN_VALUE_2>");
5values.add(value);
6
7InsertRequest insertRequest = InsertRequest.builder()
8 .table("<TABLE_NAME>")
9 .values(values)
10 .returnTokens(true)
11 .continueOnError(true)
12 .build();
13
14InsertResponse insertResponse = skyflowClient.vault("<VAULT_ID>").insert(insertRequest);

V1 response:

1{
2 "records": [
3 {
4 "table": "cards",
5 "fields": {
6 "skyflow_id": "16419435-aa63-4823-aae7-19c6a2d6a19f",
7 "cardNumber": "f3907186-e7e2-466f-91e5-48e12c2bcbc1",
8 "cvv": "1989cb56-63da-4482-a2df-1f74cd0dd1a5"
9 }
10 }
11 ]
12}

V2 response:

1{
2 "insertedFields": [
3 {
4 "skyflow_id": "9fac9201-7b8a-4446-93f8-5244e1213bd1",
5 "card_number": "5484-7829-1702-9110",
6 "request_index": "0"
7 }
8 ],
9 "errors": []
10}

Other operations at a glance

Every vault operation in v2 follows the same pattern: build a typed request with the request class’s builder, then pass it to the corresponding method on the vault client. The snippets below show v2 request construction.

Get:

1GetRequest getRequest = GetRequest.builder()
2 .table("<TABLE_NAME>")
3 .ids(Arrays.asList("<SKYFLOW_ID_1>", "<SKYFLOW_ID_2>"))
4 .returnTokens(true)
5 .build();
6GetResponse response = skyflowClient.vault("<VAULT_ID>").get(getRequest);

Update:

1HashMap<String, Object> data = new HashMap<>();
2data.put("skyflowId", "<SKYFLOW_ID>");
3data.put("card_number", "<NEW_VALUE>");
4
5UpdateRequest updateRequest = UpdateRequest.builder()
6 .table("<TABLE_NAME>")
7 .data(data)
8 .returnTokens(true)
9 .build();
10UpdateResponse response = skyflowClient.vault("<VAULT_ID>").update(updateRequest);

Delete:

1DeleteRequest deleteRequest = DeleteRequest.builder()
2 .table("<TABLE_NAME>")
3 .ids(Arrays.asList("<SKYFLOW_ID_1>", "<SKYFLOW_ID_2>"))
4 .build();
5DeleteResponse response = skyflowClient.vault("<VAULT_ID>").delete(deleteRequest);

Detokenize:

1DetokenizeRequest detokenizeRequest = DetokenizeRequest.builder()
2 .tokens(Arrays.asList("<TOKEN_1>", "<TOKEN_2>"))
3 .build();
4DetokenizeResponse response = skyflowClient.vault("<VAULT_ID>").detokenize(detokenizeRequest);

Query:

1QueryRequest queryRequest = QueryRequest.builder()
2 .query("SELECT * FROM <TABLE_NAME> WHERE skyflow_id = \"<SKYFLOW_ID>\"")
3 .build();
4QueryResponse response = skyflowClient.vault("<VAULT_ID>").query(queryRequest);

Request options

V2 moves request options onto the request builder itself instead of a separate InsertOptions object.

V1:

1InsertOptions insertOptions = new InsertOptions(true);

V2:

1InsertRequest insertRequest = InsertRequest.builder()
2 .table("<TABLE_NAME>")
3 .values(values)
4 .continueOnError(false)
5 .tokenMode(TokenMode.DISABLE)
6 .returnTokens(false)
7 .upsert("<UPSERT_COLUMN>")
8 .build();

The same builder-based pattern applies to UpsertRequest, UpdateRequest, DeleteRequest, and GetRequest.

Error handling

V2 errors carry more context to help with debugging.

V1:

1{
2 "code": "<http_code>",
3 "description": "<description>"
4}

V2:

1{
2 "httpStatus": "<http_status>",
3 "grpcCode": "<grpc_code>",
4 "httpCode": "<http_code>",
5 "message": "<message>",
6 "requestId": "<request_id>",
7 "details": ["<details>"]
8}

Use the requestId field when contacting Skyflow Support — it uniquely identifies the request for faster diagnosis.

v2.1+ updates

v2.1.0 introduces a set of backward-compatible field and method renames. Legacy forms continue to work and emit deprecation warnings.

Credential field names:

The credentials JSON file accepts both the legacy and new key names.

Legacy (still accepted)Preferred
clientIDclientId
keyIDkeyId
tokenURItokenUri

Response field names:

Response maps now return skyflowId (camelCase). The legacy skyflow_id key is still present for backward compatibility but is deprecated.

Deprecated (still returned)Preferred
skyflow_idskyflowId

Update request data key:

When calling update(), use skyflowId (camelCase) as the key in the data map to identify the record. Using skyflow_id still works but emits a deprecation warning. If both keys are present, skyflowId takes precedence.

1HashMap<String, Object> data = new HashMap<>();
2data.put("skyflowId", "<SKYFLOW_ID>"); // Preferred
3data.put("card_number", "<NEW_VALUE>");
4
5UpdateRequest request = UpdateRequest.builder()
6 .table("<TABLE_NAME>")
7 .data(data)
8 .returnTokens(true)
9 .build();
10
11skyflowClient.vault("<VAULT_ID>").update(request);

Method renames:

The following instance methods have been renamed for consistency. The old names still work but emit deprecation warnings.

Deprecated (still works)Preferred
skyflowClient.updateLogLevel(level)skyflowClient.setLogLevel(level)
TokenMode.getBYOT()TokenMode.getByot()
DetokenizeRequest.builder().downloadURL(b)DetokenizeRequest.builder().downloadUrl(b)

For the full list of changes, see the Java SDK releases on GitHub.

Get help

If you hit issues during migration, contact Skyflow Support and include the requestId from any failed call.