Quickstart — Gankpo Gateway in fifteen minutes.

This guide starts from a fresh development workstation and ends with the issuance of a signed .gkp document through the Gankpo Gateway REST API. Prerequisites: Docker and curl.

Section 1 — Start the Gateway

docker pull registry.gankpo.com/gateway:latest
docker run -d \
  --name gankpo-gateway \
  -p 8080:8080 \
  -v $(pwd)/data:/var/lib/gankpo \
  registry.gankpo.com/gateway:latest

Check that the Gateway is responding:

curl http://localhost:8080/health
# {"status":"ok","version":"..."}

Section 2 — Generate a publisher key pair

curl -X POST http://localhost:8080/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"alg":"Ed25519","label":"demo"}'

Response:

{
  "kid": "k_01HN...",
  "alg": "Ed25519",
  "public_key": "MCowBQYDK2VwAy..."
}

Keep the returned kid.

Section 3 — Get an API token

curl -X POST http://localhost:8080/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"demo","client_secret":"<your-secret>"}'

The returned token is a JWT RS256 signed by the Gateway. It must be included in the Authorization: Bearer <token> header on subsequent calls.

Section 4 — Seal a document

curl -X POST http://localhost:8080/v1/documents/seal \
  -H "Authorization: Bearer <token>" \
  -F "file=@contract.pdf" \
  -F "kid=k_01HN..." \
  -F "mime=application/pdf" \
  -o contract.gkp

The contract.gkp file is now a sealed document, verifiable offline by Gankpo Reader.

Section 5 — Verify through the Gateway

curl -X POST http://localhost:8080/v1/documents/verify \
  -H "Authorization: Bearer <token>" \
  -F "file=@contract.gkp"

Response on success:

{
  "status": "valid",
  "issuer": "k_01HN...",
  "issued_at": "2026-04-20T10:15:00Z",
  "payload_hash": "blake3:..."
}

Section 6 — Going further