Generate cryptographic key pair using HSM

POST /auth/create-key
Bearer auth

One-time setup endpoint that generates a seed public key from HSM using BIP44 derivation. The user then derives their final key pair locally using this seed.

application/json

Body Required

  • ledgerPath string Required

    Ledger path for key derivation (e.g., "NZD/main")

  • secretNumber string Required

    User's secret number (4-6 digits)

    Format should match the following pattern: ^\d{4,6}$.

Responses

  • 201 application/json

    Key generated successfully

    Hide response attributes Show response attributes object
    • success boolean
    • seedPublicKey string

      HSM-derived seed public key for local key derivation

    • keyId string(uuid)

      Unique identifier for the key derivation

    • message string
  • 400 application/json

    Invalid request parameters

    Hide response attributes Show response attributes object
    • success boolean
    • error string

      Error message

    • errorCode string

      Machine-readable error code

    • details object

      Additional error details

    • timestamp string(date-time)

      When the error occurred
  • 401

    Unauthorized - invalid authentication token

  • 429

    Rate limit exceeded

  • 500 application/json

    Internal server error

    Hide response attributes Show response attributes object
    • success boolean
    • error string

      Error message

    • errorCode string

      Machine-readable error code

    • details object

      Additional error details

    • timestamp string(date-time)

      When the error occurred
POST /auth/create-key 
curl \
 --request POST 'https://pay-api.aiic.nz/v1/auth/create-key' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"ledgerPath":"NZD/main","secretNumber":"1234"}'
Request examples 
{
  "ledgerPath": "NZD/main",
  "secretNumber": "1234"
}
Response examples (201) 
{
  "success": true,
  "seedPublicKey": "04a1b2c3d4e5f6...",
  "keyId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Use this seed public key to derive your key pair locally"
}
Response examples (400) 
{
  "success": false,
  "error": "Invalid request parameters",
  "errorCode": "INVALID_PARAMETERS",
  "details": {},
  "timestamp": "2025-05-04T09:42:00Z"
}
Response examples (500) 
{
  "success": false,
  "error": "Invalid request parameters",
  "errorCode": "INVALID_PARAMETERS",
  "details": {},
  "timestamp": "2025-05-04T09:42:00Z"
}