Key Management

Optropic uses Ed25519 public key cryptography for code signing. You can register your own signing keys or use Optropic-managed keys.

Endpoints

Method	Endpoint	Description
GET	/api/v1/keys	List all registered public keys
POST	/api/v1/keys	Register a new public key
GET	/api/v1/keys/:keyId	Get a specific key
DELETE	/api/v1/keys/:keyId	Revoke a key

---

List Keys

GET /api/v1/keys

List all public keys registered to your account.

Request

curl -X GET https://api.optropic.com/api/v1/keys \
  -H "x-api-key: optr_live_YOUR_KEY"

Response

{
  "keys": [
    {
      "keyId": "key_abc123",
      "publicKey": "302a300506032b6570032100...",
      "label": "Production Signing Key",
      "gtin": "04260799580008",
      "batchId": "BATCH-A",
      "isActive": true,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "total": 1
}

---

Register Key

POST /api/v1/keys

Register a new Ed25519 public key for code signing.

Request Body

Parameter	Type	Required	Description
publicKey	string	Yes	Hex-encoded Ed25519 public key (32 bytes = 64 hex chars)
label	string	No	Human-readable label
gtin	string	No	Restrict key to specific GTIN
batchId	string	No	Restrict key to specific batch

Example

curl -X POST https://api.optropic.com/api/v1/keys \
  -H "x-api-key: optr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a",
    "label": "Production Key 2026",
    "gtin": "04260799580008"
  }'

Response (201 Created)

{
  "keyId": "key_def456",
  "publicKey": "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a",
  "label": "Production Key 2026",
  "gtin": "04260799580008",
  "isActive": true,
  "createdAt": "2026-02-18T10:30:00Z"
}

---

Get Key

GET /api/v1/keys/:keyId

Retrieve details for a specific key.

Request

curl -X GET https://api.optropic.com/api/v1/keys/key_abc123 \
  -H "x-api-key: optr_live_YOUR_KEY"

Response

{
  "keyId": "key_abc123",
  "publicKey": "302a300506032b6570032100...",
  "label": "Production Signing Key",
  "gtin": "04260799580008",
  "batchId": null,
  "isActive": true,
  "createdAt": "2026-01-15T10:00:00Z",
  "revokedAt": null,
  "codesGenerated": 15420
}

---

Revoke Key

DELETE /api/v1/keys/:keyId

Revoke a public key. Codes signed with this key will still verify but may show a warning.

Request

curl -X DELETE https://api.optropic.com/api/v1/keys/key_abc123 \
  -H "x-api-key: optr_live_YOUR_KEY"

Response (200 OK)

{
  "keyId": "key_abc123",
  "isActive": false,
  "revokedAt": "2026-02-18T10:30:00Z"
}

Revocation is Permanent

Revoking a key cannot be undone. Codes signed with revoked keys will continue to verify but may be flagged as SUSPICIOUS.

---

Generating Ed25519 Keys

You can generate Ed25519 key pairs using standard cryptographic libraries:

Node.js

import { generateKeyPairSync } from 'crypto';

const { publicKey, privateKey } = generateKeyPairSync('ed25519');

// Export public key as hex
const publicKeyHex = publicKey
  .export({ type: 'spki', format: 'der' })
  .toString('hex');

console.log('Public Key (hex):', publicKeyHex);
// Register this with POST /api/v1/keys

Python

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives import serialization

private_key = Ed25519PrivateKey.generate()
public_key = private_key.public_key()

public_key_bytes = public_key.public_bytes(
    encoding=serialization.Encoding.Raw,
    format=serialization.PublicFormat.Raw
)

print('Public Key (hex):', public_key_bytes.hex())

OpenSSL

# Generate private key
openssl genpkey -algorithm ed25519 -out private.pem

# Extract public key
openssl pkey -in private.pem -pubout -out public.pem

# Get hex representation
openssl pkey -in public.pem -pubin -text -noout

Key Best Practices

1. Rotate keys annually — Create new keys and phase out old ones
2. Use GTIN/batch restrictions — Limit key scope when possible
3. Secure private keys — Store in HSMs or secure key vaults
4. Monitor key usage — Check codesGenerated regularly
5. Have a revocation plan — Know how to revoke compromised keys quickly