Coincover Keys API

openapi: 3.2.0
info:
  title: Coincover Keys API
  x-refined-note:
  - x-authored-by differs across the merged source definitions and was not carried
  - x-engine differs across the merged source definitions and was not carried
  - x-evidence-tiers differs across the merged source definitions and was not carried
  - x-generated differs across the merged source definitions and was not carried
  - x-generated-from differs across the merged source definitions and was not carried
  - x-generator differs across the merged source definitions and was not carried
  - x-provenance differs across the merged source definitions and was not carried
  - x-sources differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Keys across 4 of this provider''s published API definitions: coincover-institutional-openapi-openapi.json, coincover-retail-openapi-openapi.json, coincover-wallet-provider-openapi-openapi.json, coincover-openapi-generated.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://service.uat-keys.coincover.com
  description: Sandbox (UAT)
- url: https://service.keys.coincover.com
  description: Production — confirm host with your account manager
- url: https://orchestrator.control.coincover.com
  description: Production server
- url: https://orchestrator.uat-control.coincover.com
  description: Development server
tags:
- name: Keys
  description: Generate, assign, and verify cryptographic keys.
paths:
  /v1/keys:
    post:
      summary: Assign a new key
      description: Creates a new key pair with the enclave, shards the private key, and securely stores the encrypted key shards. organisation and package are optional; key_environment defaults to HOT if omitted.
      operationId: assignKey
      tags:
      - Keys
      parameters:
      - name: Authorization
        in: header
        description: Bearer token for authentication. Can be either a JWT token or API key.
        required: true
        schema:
          $ref: '#/components/schemas/Authorization'
      requestBody:
        description: Key assignment details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignKeyRequest'
      responses:
        '200':
          description: Key successfully assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignKeyResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
    servers:
    - url: https://service.uat-keys.coincover.com
      description: Sandbox (UAT)
    - url: https://service.keys.coincover.com
      description: Production — confirm host with your account manager
  /v1/keys/{keyId}/verify:
    get:
      summary: Verify a key's integrity
      description: Verifies that a key's shards can be reconstructed and that the key pair is valid.
      operationId: verifyKey
      tags:
      - Keys
      parameters:
      - name: keyId
        in: path
        description: ID of the key to verify
        required: true
        schema:
          $ref: '#/components/schemas/keyId'
      - name: Authorization
        in: header
        description: Bearer token for authentication. Can be either a JWT token or API key.
        required: true
        schema:
          $ref: '#/components/schemas/Authorization'
      responses:
        '200':
          description: Key verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyKeyResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Key not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
    servers:
    - url: https://service.uat-keys.coincover.com
      description: Sandbox (UAT)
    - url: https://service.keys.coincover.com
      description: Production — confirm host with your account manager
  /v1/key/generate:
    post:
      summary: Generate a cryptographic key
      description: Generates a new cryptographic key for a user. Requires a user identifier and a verification_id that exists in the identity_verifications table and belongs to the user associated with the organisation. This endpoint calls the hot-keys orchestrator partner-assign-key endpoint.
      operationId: generateKey
      tags:
      - Keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyGenerateRequest'
      responses:
        '200':
          description: Key generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyGenerateResponse'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
    servers:
    - url: https://orchestrator.control.coincover.com
      description: Production server
    - url: https://orchestrator.uat-control.coincover.com
      description: Development server
  /v1/partner/keys:
    post:
      summary: Partner - Assign a new key with environment specification
      description: 'Creates a new key pair with the enclave, shards the private key, and securely stores the encrypted key shards. Includes key environment specification: HOT (online generation/storage) or COLD (offline generation/storage). Partner-only endpoint.'
      operationId: partnerAssignKey
      tags:
      - Keys
      parameters:
      - name: Authorization
        in: header
        description: Bearer token for authentication. Can be either a JWT token or API key.
        required: true
        schema:
          $ref: '#/components/schemas/Authorization'
      requestBody:
        description: Key assignment details with key environment specification
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerAssignKeyRequest'
      responses:
        '200':
          description: Key successfully assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAssignKeyResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Token lacks partner-endpoint scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Key already assigned for this user and organisation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearerAuth: []
    servers:
    - url: https://service.uat-keys.coincover.com
      description: Sandbox (UAT)
    - url: https://service.keys.coincover.com
      description: Production — confirm host with your account manager
components:
  schemas:
    VerifyKeyResponse:
      type: object
      properties:
        message:
          type: string
          description: Verification status message
        is_key_valid:
          type: boolean
          description: Whether the key is valid and can be used
    AssignKeyResponse:
      type: object
      properties:
        key_id:
          type: string
          format: uuid
          description: Unique identifier for the key
        public_key:
          type: string
          description: Public key in hex format. For rsa4096 this is the encryption public key; for secp256k1 or ed25519 this is the compressed public key.
        signature:
          type: string
          description: Signature of the key in base64 format, produced by the generating enclave. Verify against CoinCover's published JWKS before relying on the key. When sign_with is supplied the signature is computed over signed_payload; otherwise it covers the public key.
        signed_payload:
          type: string
          description: JCS-canonical (RFC 8785) JSON string that was signed — object keys sorted, always including public_key alongside the requested context fields. Returned only when sign_with was supplied. Verify the signature over these exact bytes rather than a re-serialised copy.
        signed_fields:
          type: array
          description: The sign_with field names that were included, in the order requested (public_key is not listed). Confirm this contains every field you expected before trusting the binding.
          items:
            type: string
        customer_id:
          type:
          - string
          - 'null'
          description: External customer identifier (e.g. organisation customer ID)
        package_id:
          type:
          - string
          - 'null'
          description: External package identifier (e.g. workspace/package ID)
        metadata:
          type: object
          description: Optional metadata describing the associated organisation and package
          properties:
            customer_name:
              type:
              - string
              - 'null'
              description: Human-readable name of the customer or organisation
            package_name:
              type:
              - string
              - 'null'
              description: Human-readable name of the associated package or workspace
    AssignKeyRequest:
      type: object
      required:
      - user_identifier
      - key_type
      properties:
        user_identifier:
          type: string
          description: Unique identifier of the user
        key_type:
          type: string
          enum:
          - rsa4096
          - secp256k1
          - ed25519
          description: Type of cryptographic key to generate. rsa4096 for encrypting recovery material; secp256k1 or ed25519 for a blockchain backup signer.
        key_environment:
          type: string
          enum:
          - HOT
          - COLD
          default: HOT
          description: Key environment specification - HOT (online generation) or COLD (offline generation)
        organisation:
          type: object
          description: Optional organisation metadata
          properties:
            customer_id:
              type: string
              description: Unique identifier for the organisation
            customer_name:
              type: string
              description: Name of the organisation customer
        package:
          type: object
          description: Optional package metadata
          properties:
            package_id:
              type: string
              description: External package ID assigned to the key
            package_name:
              type: string
              description: Name of the package
        sign_with:
          type: array
          description: Optional list of context fields to bind into the enclave signature. When present, the enclave signs a JCS-canonical (RFC 8785) JSON payload built from these fields plus the public_key (always included), returned as signed_payload, so a verified signature attests to the business context the key was issued for — not just the key bytes. Do not list public_key here; it is included implicitly.
          items:
            type: string
            enum:
            - external_customer_id
            - external_package_id
            - pulled_by_id
            - pulled_by_type
            - user_id
            - key_id
            - key_fingerprint
    keyId:
      type: string
      format: uuid
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        error:
          type: string
          description: Error type
    Authorization:
      type: string
    KeyGenerateResponse:
      type: object
      properties:
        key_id:
          type: string
          format: uuid
          description: Unique identifier for the generated key (UUID)
          example: 550e8400-e29b-41d4-a716-446655440000
        public_key:
          type: string
          description: Public key in hexadecimal format
          example: 30820122300d06092a864886f70d...
        signature:
          type: string
          description: Base64 ECDSA P-256 DER signature. When sign_with is omitted, this signs the bare public_key hex; otherwise it signs signed_payload. Verify it against CoinCover's published JWKS, not with public_key.
          example: MEUCIQDxyz123abc456def789ghi...
        signed_payload:
          type: string
          description: RFC 8785 JCS-canonical JSON string signed by the enclave. Present only when sign_with was supplied. Verify its exact UTF-8 bytes without re-stringifying.
          example: '{"external_customer_id":"acme-wallet","public_key":"30820122300d..."}'
        signed_fields:
          type: array
          description: Validated context fields included in signed_payload, in request order. Does not include public_key. Present only when sign_with was supplied.
          items:
            type: string
            enum:
            - external_customer_id
            - external_package_id
            - pulled_by_id
            - pulled_by_type
            - user_id
            - key_id
            - key_fingerprint
          example:
          - external_customer_id
          - user_id
          - key_fingerprint
      required:
      - key_id
      - public_key
      - signature
    KeyGenerateRequest:
      type: object
      properties:
        user_identifier:
          type: string
          description: User identifier (REQUIRED)
          example: john.doe@example.com
        verification_id:
          type: string
          description: Verification ID from a previous verification. (REQUIRED) Must exist in identity_verifications table and belong to the user associated with the organisation.
          example: a7b8c9d0-e1f2-4345-a678-901234567890
        sign_with:
          type: array
          description: Optional context fields to bind into the enclave signature. public_key is always signed implicitly and must not be included. Every requested field must resolve to a non-empty value, except key_fingerprint which may resolve after generation. Each field may only be listed once.
          items:
            type: string
            enum:
            - external_customer_id
            - external_package_id
            - pulled_by_id
            - pulled_by_type
            - user_id
            - key_id
            - key_fingerprint
          example:
          - external_customer_id
          - user_id
          - key_fingerprint
      required:
      - user_identifier
      - verification_id
    PartnerAssignKeyResponse:
      type: object
      properties:
        key_id:
          type: string
          format: uuid
          description: Unique identifier for the key
        public_key:
          type: string
          description: Public key in hex format
        signature:
          type: string
          description: Signature of the key in base64 format, produced by the generating enclave. Verify against CoinCover's published JWKS before encrypting recovery material. When sign_with is supplied the signature is computed over signed_payload; otherwise it covers the public key.
        signed_payload:
          type: string
          description: JCS-canonical (RFC 8785) JSON string that was signed — object keys sorted, always including public_key alongside the requested context fields. Returned only when sign_with was supplied. Verify the signature over these exact bytes rather than a re-serialised copy.
        signed_fields:
          type: array
          description: The sign_with field names that were included, in the order requested (public_key is not listed). Confirm this contains every field you expected before trusting the binding.
          items:
            type: string
        customer_id:
          type:
          - string
          - 'null'
          description: External customer identifier (e.g. organisation customer ID)
        package_id:
          type:
          - string
          - 'null'
          description: External package identifier (e.g. workspace/package ID)
        metadata:
          type: object
          description: Optional metadata describing the associated organisation and package
          properties:
            customer_name:
              type:
              - string
              - 'null'
              description: Human-readable name of the customer or organisation
            package_name:
              type:
              - string
              - 'null'
              description: Human-readable name of the associated package or workspace
    PartnerAssignKeyRequest:
      type: object
      required:
      - user_identifier
      - key_type
      - key_environment
      - organisation
      - package
      properties:
        user_identifier:
          type: string
          description: Unique identifier of the user
        key_type:
          type: string
          enum:
          - rsa4096
          - secp256k1
          - ed25519
          description: Type of cryptographic key to generate. rsa4096 for encryption of recovery material; secp256k1 or ed25519 for blockchain backup signers.
        key_environment:
          type: string
          enum:
          - HOT
          - COLD
          description: Key environment specification - HOT (online generation) or COLD (offline generation)
        organisation:
          type: object
          description: Organisation metadata
          properties:
            customer_id:
              type: string
              description: Unique identifier for the organisation
            customer_name:
              type: string
              description: Name of the organisation customer
        package:
          type: object
          description: Package metadata
          properties:
            package_id:
              type: string
              description: External package ID assigned to the key
            package_name:
              type: string
              description: Name of the package
        sign_with:
          type: array
          description: Optional list of context fields to bind into the enclave signature. When present, the enclave signs a JCS-canonical (RFC 8785) JSON payload built from these fields plus the public_key (always included), returned as signed_payload, so a verified signature attests to the business context the key was issued for — not just the key bytes. Do not list public_key here; it is included implicitly.
          items:
            type: string
            enum:
            - external_customer_id
            - external_package_id
            - pulled_by_id
            - pulled_by_type
            - user_id
            - key_id
            - key_fingerprint
    PostV1KeysRequest:
      type: object
      properties:
        key_type:
          type: string
          description: The type of key to generate, e.g., "secp256k1" or "ed25519".
      required:
      - key_type
    PostV1KeysResponse:
      type: object
      properties:
        public_key:
          type: string
          description: The compressed public key generated by CoinCover.
  securitySchemes:
    bearerAuth:
      description: Bearer token authentication. Can be either a JWT token or API key.
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication and authorization
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: ID token as Bearer token
    bearer:
      type: http
      scheme: bearer
x-refined-from:
- coincover-institutional-openapi-openapi.json
- coincover-retail-openapi-openapi.json
- coincover-wallet-provider-openapi-openapi.json
- coincover-openapi-generated.yml