API docs by Redocly

GQTW Core API (1.0.0-draft)

Download OpenAPI specification:

License: MIT

OpenAPI normative surface for GQTW wallet interoperability contracts.

This OpenAPI file is the normative endpoint contract for the GQTW profile.

Semantics:

  • All request and response payloads are JSON objects.
  • Presentation and ingest-style operations are asynchronous unless a response explicitly states otherwise.
  • GQTS host retrieval operations are defined in GQTS Core and are referenced by operation id in GQTW prose.

Versioning strategy:

  • Breaking wire changes require a new API version and migration text.
  • Profile-specific constraints are expressed through requirement ids and media types.

profile

Wallet profile metadata and capability publication.

Get wallet profile metadata.

Returns machine-readable metadata for one GQTW profile, including supported proof profiles, supported upstream host-profile operations, and conformance dependencies.

path Parameters
profileId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$

Responses

Response samples

Content type
{
  • "profileId": "string",
  • "profileVersion": "string",
  • "proofProfiles": [
    ],
  • "upstreamRequirements": [
    ],
  • "gqtsOperations": [
    ],
  • "gqscdProfileRefs": [
    ]
}

presentation

Wallet-RP presentation request and submission flows.

Submit a relying-party presentation request to a wallet endpoint.

Accepts a relying-party request that asks for one or more selectively disclosed claims. Wallet implementations MUST bind all accepted requests to explicit challenge and audience values.

Request Body schema:
required
requestId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
challenge
required
string >= 16 characters
audience
required
string non-empty
required
object (RelyingPartyDescriptor)
required
Array of objects (ClaimRequest) non-empty
selectiveDisclosureRequired
boolean
Default: true
proofProfile
string
Enum: "bbs-profile" "oprf-profile" "sd-profile" "profile-extension"
expiresAt
required
string <date-time> (IsoDateTime)

Responses

Request samples

Content type
{
  • "requestId": "string",
  • "challenge": "stringstringstri",
  • "audience": "string",
  • "relyingParty": {
    },
  • "requestedClaims": [
    ],
  • "selectiveDisclosureRequired": true,
  • "proofProfile": "bbs-profile",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "requestId": "string",
  • "status": "accepted",
  • "consentHandle": "string",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Submit a wallet presentation for a previously accepted request.

Submits the holder-approved presentation output for one presentation request. The submission payload can contain VC/VP-family artifacts and profile-defined selective disclosure proofs.

path Parameters
requestId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
Request Body schema:
required
requestId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
holderDid
required
string (DidUri) >= 8 characters ^did:[a-z0-9]+:.+$
required
object (ProofArtifactEnvelope)

VC/VP-family artifact envelope or profile-equivalent object.

Array of objects (ClaimDisclosure)
required
object (ConsentReceipt)

Responses

Request samples

Content type
{
  • "requestId": "string",
  • "holderDid": "stringst",
  • "proofArtifact": {
    },
  • "disclosedClaims": [
    ],
  • "consentReceipt": {
    }
}

Response samples

Content type
{
  • "requestId": "string",
  • "mechanicalValidity": "valid",
  • "recognitionStatus": "out-of-scope",
  • "checkedAt": "2019-08-24T14:15:22Z",
  • "failureCodes": [
    ]
}

gqts

Wallet-side integration hooks for GQTS-derived head-state changes.

Submit a compact head-state hint derived from a GQTS history view.

Accepts a compact head-state hint so wallet implementations can decide if heavier retrieval is needed. This operation does not replace authoritative retrieval from GQTS endpoints.

Request Body schema:
required
logId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
hostOrigin
required
string <uri> (Uri)
headToken
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
headDigest
required
string^[A-Za-z0-9_-]{16,}$
observedAt
required
string <date-time> (IsoDateTime)

Responses

Request samples

Content type
{
  • "logId": "string",
  • "hostOrigin": "http://example.com",
  • "headToken": "string",
  • "headDigest": "string",
  • "observedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "receiptId": "string",
  • "acceptedAt": "2019-08-24T14:15:22Z",
  • "status": "accepted"
}

gqscd

Wallet-GQSCD invocation hooks for signing, sealing, and attestation.

Invoke a GQSCD-backed signing, sealing, or attestation operation.

Invokes a protected-key operation through a GQSCD-conformant interface. User intent and user-approved object digest binding are required inputs.

Request Body schema:
required
invocationId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
operationType
required
string
Enum: "sign" "seal" "attest"
keyReference
required
string
userApprovedObjectDigest
required
string^[A-Za-z0-9_-]{16,}$
challenge
required
string >= 16 characters
audience
required
string non-empty

Responses

Request samples

Content type
{
  • "invocationId": "string",
  • "operationType": "sign",
  • "keyReference": "string",
  • "userApprovedObjectDigest": "string",
  • "challenge": "stringstringstri",
  • "audience": "string"
}

Response samples

Content type
{
  • "invocationId": "string",
  • "status": "succeeded",
  • "signatureObject": { },
  • "evidenceReferences": [
    ]
}

portability

Opaque encrypted export and import workflows.

Create an opaque encrypted portability package.

Exports wallet-private material as an encrypted opaque package. The package is designed for controlled migration and backup, not public publication.

Request Body schema:
required
exportId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
required
object
includePrivateLog
boolean
Default: true
includeArtifacts
boolean
Default: true

Responses

Request samples

Content type
{
  • "exportId": "string",
  • "recipientPublicKey": { },
  • "includePrivateLog": true,
  • "includeArtifacts": true
}

Response samples

Content type
{
  • "packageId": "string",
  • "cipherSuite": "string",
  • "ciphertext": "string",
  • "digest": "string",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Import an opaque encrypted portability package.

Imports an opaque encrypted package and performs integrity checks before activation.

Request Body schema:
required
required
object (WalletExportPackage)
object

Responses

Request samples

Content type
{
  • "package": {
    },
  • "decryptionContext": { }
}

Response samples

Content type
{
  • "status": "imported",
  • "activatedHeadToken": "string",
  • "migratedArtifactCount": 0
}

privacy

Erasure and privacy-control interfaces.

Submit a holder-scoped data-erasure request.

Submits an erasure request for data previously disclosed through wallet-mediated presentation flows.

Request Body schema:
required
requestId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
relyingPartyId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
legalBasis
string
Default: "gdpr-article-17"
proofOfInteraction
string
submittedAt
required
string <date-time> (IsoDateTime)

Responses

Request samples

Content type
{
  • "requestId": "string",
  • "relyingPartyId": "string",
  • "legalBasis": "gdpr-article-17",
  • "proofOfInteraction": "string",
  • "submittedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "requestId": "string",
  • "status": "accepted",
  • "reference": "string"
}

incident

Signed incident reporting for conflict or abuse evidence.

Submit a signed incident report.

Submits signed evidence about host conflicts, replay attempts, policy abuse, or profile violations.

Request Body schema:
required
reportId
required
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
incidentType
required
string
Enum: "host-divergence" "fork-detected" "replay-attempt" "policy-abuse" "profile-violation"
affectedHost
string <uri> (Uri)
affectedLogId
string (Identifier) [ 1 .. 128 ] characters ^[A-Za-z0-9._:-]+$
reporterDid
string (DidUri) >= 8 characters ^did:[a-z0-9]+:.+$
reportedAt
required
string <date-time> (IsoDateTime)
required
Array of objects (IncidentEvidenceItem) non-empty
object

Responses

Request samples

Content type
{
  • "reportId": "string",
  • "incidentType": "host-divergence",
  • "affectedHost": "http://example.com",
  • "affectedLogId": "string",
  • "reporterDid": "stringst",
  • "reportedAt": "2019-08-24T14:15:22Z",
  • "evidence": [],
  • "signature": { }
}

Response samples

Content type
{
  • "receiptId": "string",
  • "acceptedAt": "2019-08-24T14:15:22Z",
  • "status": "accepted"
}