Before You Integrate: Control-Plane Prerequisites

SDK Version: 3.0.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 (the Admin Console or the ankasecure-admin 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 row lists both the Admin Console path and the equivalent ankasecure-admin command.

2.1 Tenant

The isolation boundary that owns every other object. Provisioned by a platform administrator, then activated.

• Admin Console: platform-admin context → Tenant provisioning (see Tenant Management^*).

• admin-cli:

  ankasecure-admin platform tenant provision --name "Acme Corp" --slug acme
  ankasecure-admin platform tenant activate --slug acme
  

2.2 Application (client-credentials holder)

An application is the client-credentials principal your SDK authenticates as. Its client_id and client_secret are exactly the values you pass to authenticateApplication(clientId, clientSecret).

• Admin Console: Application Management^*.

• admin-cli (returns client_id + client_secret — capture the secret, it is shown once):

  ankasecure-admin application create --name "Payments Pipeline"
  

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.

• Admin Console: managed as part of the organization model alongside Key Management^*; see the Cryptographic Actor entity for the model.

• admin-cli:

  ankasecure-admin actor create --name "payments-service"
  ankasecure-admin actor assign-role --id <ACTOR_ID> --role secure.encrypt
  

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^*.

  • admin-cli:

    ankasecure-admin key create \
        --algorithm ML-KEM-768 \
        --label payments-encryption-key \
        --capability encrypt --capability decrypt
    

• Import a legacy keystore (JKS / PKCS#12) — this path is Admin Console / admin-api only; the ankasecure-admin CLI has no keystore-import subcommand.

  • 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.
  • 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^*.

• admin-cli: the path to a grant is the exchange lifecycle — reaching the ACTIVE state materializes the capability grant (1:1):

  ankasecure-admin exchange create --context-id <CTX_ID> --kid <KEY_ID> --label "payments-grant"
  ankasecure-admin exchange validate --id <EXCHANGE_ID>
  ankasecure-admin exchange activate --id <EXCHANGE_ID>
  

  (exchange-context create provisions the <CTX_ID> first.)

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 the tenant (platform admin):

   ankasecure-admin platform tenant provision --name "Acme Corp" --slug acme
   ankasecure-admin platform tenant activate --slug acme
   

2. Create the application (tenant admin) and capture the returned client_id / client_secret:

   ankasecure-admin context use --tenant acme
   ankasecure-admin application create --name "Payments Pipeline"
   

3. Create the actor and assign a role:

   ankasecure-admin actor create --name "payments-service"
   ankasecure-admin actor assign-role --id <ACTOR_ID> --role secure.encrypt
   

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

   ankasecure-admin key create \
       --algorithm ML-KEM-768 \
       --label payments-encryption-key \
       --capability encrypt --capability decrypt
   

   …or import a legacy keystore through the Admin Console Import Keystore tab. 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 / exchange wizard, or the admin-cli exchange lifecycle):

   ankasecure-admin exchange create --context-id <CTX_ID> --kid <KEY_ID> --label "payments-grant"
   ankasecure-admin exchange validate --id <EXCHANGE_ID>
   ankasecure-admin exchange activate --id <EXCHANGE_ID>
   

6. Configure the SDK with the host, port, and application credentials from step 2 (see §5).

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.
• Admin CLI Commands^* — the full control-plane command reference.
• Deployment Organization Model — actors, assets, capabilities, and grants.