> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Register Key
> Registers a new cryptographic key for an issuer. Supports ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512, and Ed25519.
Registers a new cryptographic signing key for an issuer. Keys start in ACTIVE status and can be used immediately for signing attestations.
### Supported Algorithms
| Algorithm | Type | Use Case |
| --------- | --------------- | --------------------------------------------------------------------------- |
| Ed25519 | EdDSA | Default. Fastest signatures, smallest keys. Recommended for most use cases. |
| ES256 | ECDSA P-256 | Widely supported. Compatible with WebCrypto, mobile SDKs. |
| ES384 | ECDSA P-384 | Government/CNSA Suite. Required for some procurement contracts. |
| ES512 | ECDSA P-521 | Maximum ECDSA security. Larger signatures. |
| RS256 | RSA PKCS#1v1.5 | Legacy compatibility. Interop with older PKI systems. |
| RS384 | RSA SHA-384 | Higher security RSA with SHA-384. |
| RS512 | RSA SHA-512 | Higher security RSA with SHA-512. |
| PS256 | RSA-PSS | Modern RSA. NIST recommended replacement for PKCS#1v1.5. |
| PS384 | RSA-PSS SHA-384 | Higher security RSA-PSS. |
| PS512 | RSA-PSS SHA-512 | Maximum RSA security. |
Ed25519 is the default and recommended for new projects. Use ES384 for government/regulated industries. Use PS256 over RS256 for new RSA deployments. RS256 is available for backward compatibility only.
### Parameters
The UUID of the issuer to register the key for
Unique key identifier (e.g., "ed-key-1")
Signing algorithm. One of: `Ed25519`, `ES256`, `ES384`, `ES512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`.
Base64-encoded public key
### Responses
## OpenAPI
````yaml mint-openapi.yaml POST /v1/issuers/{id}/keys
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/issuers/{id}/keys:
post:
tags:
- Keys
summary: Register Key
description: >-
Registers a new cryptographic key for an issuer. Supports ES256, ES384,
ES512, RS256, RS384, RS512, PS256, PS384, PS512, and Ed25519.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- kid
- algorithm
- public_key
properties:
kid:
type: string
algorithm:
$ref: '#/components/schemas/SigningAlgorithm'
public_key:
type: string
description: Base64-encoded public key
expires_at:
type: string
format: date-time
example:
kid: es256-key-1
algorithm: ES256
public_key: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
responses:
'201':
description: Key registered
content:
application/json:
schema:
$ref: '#/components/schemas/Key'
'400':
description: Invalid algorithm or key format
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
code: VALIDATION_ERROR
message: >-
Unsupported algorithm. Must be one of: ES256, ES384, ES512,
RS256, RS384, RS512, PS256, PS384, PS512, Ed25519
http_status: 400
security:
- APIKey: []
- BearerAuth: []
components:
schemas:
SigningAlgorithm:
type: string
enum:
- Ed25519
- ES256
- ES384
- ES512
- RS256
- RS384
- RS512
- PS256
- PS384
- PS512
description: Signing algorithm for key generation
Key:
type: object
properties:
kid:
type: string
description: Key identifier
issuer_id:
type: string
format: uuid
algorithm:
$ref: '#/components/schemas/SigningAlgorithm'
public_key:
type: string
description: Base64-encoded public key
status:
type: string
enum:
- ACTIVE
- DISABLED
- EXPIRED
not_before:
type: string
format: date-time
expires_at:
type: string
format: date-time
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT for user-initiated operations
````