Skip to content

The Developer Hub

Audience: an integrator writing code against an ANKASecure© deployment that already exists
Reading time: 5 minutes
Where it lives: apidocs.ankatech.co

The Developer Hub is a separate documentation surface from this site. It is where the API is documented operation by operation — request schema, response schema, error codes, copy-ready code samples, and a request panel that executes the call for real against a demo tenant.

This page is the way in. It explains what the Hub is, how you get access, which of the platform's documentation surfaces answers which kind of question, and when to reach for HTTP, the SDK, or a CLI instead.

🚀 Getting Started on the Hub 📖 API Reference 🍳 Recipes

What this page owns

More than one surface can describe the API, so it is worth being explicit about which one owns what. This page orients and routes. It does not reproduce the contract.

It names capability areas — the questions the reference is organised around — and never individual endpoints, verbs, request fields or per-operation scopes. Those live in exactly one place: the API definition the Hub is generated from, and the OpenAPI document the deployment you are calling actually serves.

The asymmetry is the reason. A capability area that has been renamed costs you one extra click. An endpoint copied into a second document and left behind costs you a 404 and a wrong belief about the platform — and there is no build that can tell you which of the two copies is the stale one. So the routing lives here, and the contract lives where it is generated.

Which surface answers which question

You want to know Go to Notes
The exact request and response of one operation, and to run it Developer Hub — apidocs.ankatech.co Generated from the API definition; carries the request panel
Why the platform is shaped the way it is, and how to design your integration This site — start at Platform Overview and Key Concepts Concepts, integration guides, SDK and CLI pages
What a failure means and what to do about it This site — Error Reference One page per type URI the platform emits
The base URL of the deployment you are on, and the credential you hold Admin Console → API Reference Only that screen knows which environment you signed in to
A machine-readable contract to generate a client from OpenAPI specifications The vendored core, auth and pqc documents

Getting in

Reading the Hub needs nothing — it is open. Running a call from it needs a tenant.

  1. Open the Hub. apidocs.ankatech.co lands on the guides; the left sidebar carries the reference and the recipes. Search covers all three and is bound to Ctrl+K (⌘+K on macOS).
  2. Get a demo tenant. The request panel is pre-pointed at the ANKATech demo environment. To be given a tenant, an application credential and — if you want one — a demo user account, write to [email protected] describing what you intend to build, so the demo tenant can be scoped to it.
  3. Exchange the credential for a token. Authentication is OAuth 2.0; a machine integration uses the client_credentials grant against the deployment's token endpoint and sends the result as a Bearer token on every subsequent call. The Authentication reference carries the request and the response.
  4. Call something. Encrypting a short payload with a key that already exists is the shortest round trip that proves the whole chain — credential, token, scope, key, operation.

Provision before you operate

The Hub documents the data plane: operations on tenants, keys and grants that already exist. Creating them is control-plane work, done from the Admin Console, the ankasecure-admin CLI, or the Admin SDK. If a first call fails and nothing looks wrong with the request, the usual cause is that the object it names has not been provisioned yet — see Before You Integrate: Control-Plane Prerequisites.

The reference, by the question you are asking

The reference is organised by capability. Open it and use the sidebar; the areas below are the questions each one answers.

Your question Area of the reference
How do I get a token, and what is in it? Authentication
Encrypt, decrypt, sign, verify, re-encrypt, re-sign — compact JOSE Secure
The same operations, for payloads too large to send in one body Secure Streaming
Which keys can I see, and what are their properties? Key Query, Key Metadata
Which algorithms may I use on this deployment? Algorithm Catalog
Bring existing keys and artifacts in; produce artifacts other systems can read Migration, Interoperability
Create, rotate, revoke a key Key Creation, Key Lifecycle — but read the note below
What is the policy engine resolving and caching for my tenant? Policy Cache Monitoring
What has my tenant consumed against its licence? License Metrics

Key lifecycle is control-plane work

Creating, rotating and revoking a key are control-plane operations. The Core API carries handlers for them, but on the current platform they are withheld from the published API surface, and the scopes that gate them are not among those issued to an ordinary integrator credential. Drive key lifecycle from the Admin Console, the ankasecure-admin CLI, or the Admin SDK instead.

More generally: the Hub is generated from an API definition, and a deployment can be ahead of it or behind it. Where the two disagree, the OpenAPI document served by the deployment you are calling is the authority.

Recipes: start from a finished workflow

A per-operation reference tells you what each call does; it does not tell you how to chain them. Recipes are end-to-end flows that start from a real integration problem and walk every call it needs — a first encrypt-and-decrypt against a fresh key, sign-then-encrypt, migrating data from a classical key to a post-quantum one by re-encryption, rotating a composite hybrid key, streaming a large re-encryption, onboarding a legacy keystore.

Adapt a finished flow rather than assembling one from the reference. The same ground is covered for Java callers by the SDK integration flows.

When to use HTTP, the SDK, or a CLI

All three reach the same API and return the same payloads. The choice is about what you are building, not about capability.

Use When
HTTP directly Your language has no ANKASecure client, or you are embedding calls in something that already speaks HTTP. The Hub is written for exactly this reader
Java SDK You are integrating from a JVM application and want a typed client, streaming helpers, and the JOSE handling done for you
ankasecure-crypto CLI Scripts, CI/CD jobs, batch work and one-off operations, with no code to write

Provisioning — tenants, credentials, keys, grants, policies — is separate from all three and is described in Control-Plane Prerequisites.

Reading a failure

Every API error is RFC 9457 Problem Details, returned as application/problem+json. RFC 9457 obsoleted RFC 7807 in July 2023; the media type and the five defined members are unchanged, so a client written against RFC 7807 needs no change.

The member to branch on is type — a stable URI that identifies the problem. Do not parse detail, and do not treat the HTTP status as the identifier: several distinct problems share a status.

Every type the platform emits has a page of its own explaining what caused it and what to do next. Start at the Error Reference.

Limits: read them at runtime, not from a document

Two numbers that integrations tend to hard-code are operator settings, so any value written into a document is a snapshot of one deployment.

Payload size. The producer operations — encrypt, sign, and the combined sign-then-encrypt form — enforce a maximum plaintext length. The platform ships with a default of 4,000,000 bytes, but an operator can change it per deployment and per tenant, and the change takes effect without a restart. The value your tenant is actually held to is what GET /api/v3/crypto/limits returns: call it once at startup and size or chunk your requests from that, rather than discovering the ceiling as a 413. For payloads above it, use the streaming operations.

Token lifetime. Access tokens are short-lived and refresh tokens are longer-lived; the shipped defaults are 15 minutes and 8 hours, and both are set per environment. Treat the token's own exp claim as the authority, refresh ahead of it, and re-authenticate on a 401 — never on a timer derived from a number you read here.

Where to go next