Before You Integrate: Control-Plane Prerequisites

SDK Version: 3.4.0 Audience: Integration developers wiring the SDK into an application

The AnkaSecure SDK is a data-plane client. It performs cryptographic operations — encrypt, decrypt, sign, verify, re-encrypt, re-sign, PKCS#7/JOSE interop — on objects that already exist. It does not create tenants, applications, actors, keys, or authorization grants. Every object the SDK touches must first be provisioned in the control plane: by people in the Admin Console, or, for keys and grants, by an administrative workload through the Key Management SDK or CLI.

If you call authenticateApplication(...) or encrypt(...) before the underlying tenant, credentials, keys, and capability grants exist, the call fails at the server — not because of an SDK bug, but because there is nothing to operate on yet. This page lists exactly what must exist first, and the control-plane tool that creates each piece.

1. The Two Planes

AnkaSecure separates provisioning from operation. This is the single most important thing to understand before integrating.

The SDK lives entirely in the data plane. Its read-only key access (listKeys, listAllKeys, getKeyMetadata, getSupportedAlgorithms) lets you discover what has been provisioned, but it can never create or modify a key.

2. What Must Exist Before Your First SDK Call

Provision these in order. Each step names the Admin Console path and, where an administrative workload can do it, the equivalent ankasecure-km command.

2.1 Tenant

The isolation boundary that owns every other object. Provisioned and activated by a platform administrator in the Admin Console (see Tenant Management^*).

2.2 Application, and the Actor that holds the credential

An application groups the identities your integration uses; it holds no credential of its own and cannot authenticate. The principal your SDK authenticates as is a Cryptographic Actor belonging to that application: the actor is what carries a credential, and the client_id you pass to authenticateApplication(clientId, clientSecret) is the actor's identifier, not the application's.

Create the application first, then issue a credential to one of its actors — that issuance is what returns the secret, once. Both are done by the tenant administrator in the Admin Console (Application Management^*); the Admin API POST /api/v3/admin/tenants/{tenantId}/actors/{actorId}/credentials mints the actor's client_secret and returns it once.

2.3 Actor (machine principal) and roles

An actor is the cryptographic principal that holds authorization. Role assignments determine which API scopes the principal carries, which in turn gate the operations it can request.

The tenant administrator creates the actor and assigns its roles in the Admin Console, as part of the organization model alongside Key Management^*; see the Cryptographic Actor entity for the model.

2.4 Keys (Cryptographic Assets)

The SDK operates on keys by their kid. You either create a fresh key or import an existing keystore.

• Create —

  • Admin Console: Key Management^*.

  • Key Management CLI:

    ankasecure-km keys create \
        --kid payments-encryption-key \
        --kty ML-KEM --algorithm ML-KEM-768 \
        --purpose ENCRYPT_DECRYPT
    

• Import a legacy keystore (JKS / PKCS#12) —

  • Admin Console: the Import Keystore tab of Key Management^*. Import produces one kid per keystore alias as <prefix><alias> (the UI concatenates the prefix and the alias verbatim — a trailing - in the prefix yields a double dash, e.g. prefix pkcs7 + alias cifrado → pkcs7-cifrado). Where an alias's KeyUsage is ambiguous you must pick its purpose explicitly (ENCRYPT_DECRYPT or SIGN_VERIFY), otherwise the import returns 422 purpose-required.
  • Key Management CLI: ankasecure-km keys import-keystore --keystore-file <path> --metadata-file <json> --password-prompt.
  • Admin API: POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore, the same operation the console tab performs.

2.5 Capability Grants

A capability grant is the runtime unit of authorization. It binds an Actor + a Capability + one or more Cryptographic Assets (plus an optional Exchange Context and Constraints). Without an ACTIVE grant on the target kid, the actor's operation is refused even if it authenticated successfully. See the Capability Grant entity reference for the authoritative model.

• Admin Console: create a capability grant directly, or drive the exchange wizard, from Key Management^*.

• Key Management CLI: create the grant directly, or drive the exchange lifecycle — reaching the ACTIVE state materializes the capability grant (1:1):

  ankasecure-km capability-grants create --body-file grant.json
  # or
  ankasecure-km exchanges create --body-file exchange.json
  ankasecure-km exchanges validate --id <EXCHANGE_ID>
  ankasecure-km exchanges activate --id <EXCHANGE_ID> --expected-version <n>
  

3. Operation → Capability Grant Matrix

For each data-plane SDK operation, the actor must hold the listed capability on the target kid. Cross-kid operations need a grant on both keys.

The full capability enum is ENCRYPT, DECRYPT, SIGN, VERIFY, REENCRYPT, RESIGN, WRAP, UNWRAP, DERIVE.

4. Zero to First Operation (End-to-End)

A complete walkthrough that crosses both planes, from an empty platform to a working encrypt call.

1. Provision and activate the tenant (platform administrator, Admin Console).

2. Create the application and the actor, assign its role and issue its credential (tenant administrator, Admin Console). The credential issuance returns the client_secret once; the actor UUID is the client_id.

3. Prepare an administrative workload for automation, if the keys and grants are managed by a program (Key Management SDK — Prerequisites).

4. Create or import the key. Either create a fresh key:

   ankasecure-km keys create \
       --kid payments-encryption-key \
       --kty ML-KEM --algorithm ML-KEM-768 \
       --purpose ENCRYPT_DECRYPT
   

   …or import a legacy keystore through the Admin Console Import Keystore tab or ankasecure-km keys import-keystore. For example, importing an alias cifrado under prefix pkcs7 yields the kid pkcs7-cifrado; resolve each alias's purpose (pick ENCRYPT_DECRYPT / SIGN_VERIFY when KeyUsage is ambiguous, or the import returns 422 purpose-required). That kid is then usable as the recipient for PKCS#7 conversion.

5. Grant the actor the needed capabilities on the key (Admin Console grant or exchange wizard, or ankasecure-km capability-grants create / the ankasecure-km exchanges lifecycle).

6. Configure the SDK with the host, port, and the actor credentials from step 2 (see SDK and example configuration).

7. Authenticate and operate (data plane):

   AnkaSecureSdk factory = new AnkaSecureSdk(properties);
   try (SecretChars secret = new SecretChars(clientSecret.toCharArray())) {
       AuthenticatedSdk sdk = factory.authenticateApplication(clientId, secret);
       EncryptResult result = sdk.encrypt("payments-encryption-key", plaintext);
   }
   

Only step 7 is the SDK's job. Steps 1-6 are all control-plane.

5. SDK and Example Configuration

The SDK reads a Properties object (typically a cli.properties file). The keys that connect it to a provisioned tenant and its keys:

The bundled example scenarios operate on a pre-provisioned demo-cli playground seeded by the ankasecure-demo-provisioning tool. For the example prerequisites (the cli-reference@demo-cli actor, the ankasecure.demo.kids catalogue, and the PKCS#7 fixture), see:

• The shared example prerequisites: --8<-- "snippets/sdk-examples/_prerequisites.md" is included by every flow page; read it on any flow page such as Flow 1.
• The Demo Provisioning Tool^* that seeds the playground.

6. Next Steps

• SDK Overview — the data-plane surface and design goals.
• SDK Usage Guide — setup, authentication, and operations.
• Key Management CLI Commands — key and grant management from the command line.
• Deployment Organization Model — actors, assets, capabilities, and grants.