GraphQL API Reference¶

Proof Keys Studio uses GraphQL for all backend operations. This document describes the available queries and mutations.

Queries¶

keys¶

Fetch keys for a user or session.

query Keys($ownerId: String!) {
  keys(ownerId: $ownerId) {
    id
    label
    algorithm
    did
    publicKeyMultibase
    createdAt
    status
    upgradedDid
    expiresAt
  }
}

Variables: - ownerId: User or session identifier

Returns: Array of key objects

recentActivity¶

Fetch recent activity events.

query RecentActivity($ownerId: String) {
  recentActivity(ownerId: $ownerId) {
    type
    message
    createdAt
    keyLabel
    keyDid
    subject
  }
}

Variables: - ownerId: Optional user or session identifier (filters events)

Returns: Array of activity event objects

Mutations¶

webauthnRegistrationBegin¶

Start WebAuthn registration.

mutation BeginRegistration($username: String!) {
  webauthnRegistrationBegin(username: $username) {
    publicKey
  }
}

Variables: - username: Username to register

Returns: Public key options for WebAuthn

webauthnRegistrationFinish¶

Complete WebAuthn registration.

mutation FinishRegistration($credential: String!, $username: String!) {
  webauthnRegistrationFinish(credential: $credential, username: $username)
}

Variables: - credential: WebAuthn credential (JSON string) - username: Username being registered

Returns: Boolean indicating success

webauthnLoginBegin¶

Start WebAuthn login.

mutation BeginLogin($username: String!) {
  webauthnLoginBegin(username: $username) {
    publicKey
  }
}

Variables: - username: Username to sign in with

Returns: Public key options for WebAuthn

webauthnLoginFinish¶

Complete WebAuthn login.

mutation FinishLogin($credential: String!, $username: String!) {
  webauthnLoginFinish(credential: $credential, username: $username)
}

Variables: - credential: WebAuthn credential (JSON string) - username: Username signing in

Returns: Boolean indicating success

sessionOpen¶

Open a user session.

mutation SessionOpen($username: String!) {
  sessionOpen(username: $username)
}

Variables: - username: Username or "ANONYMOUS"

Returns: Boolean indicating success

keyCreate¶

Create a new key.

mutation CreateKey($label: String!, $alg: DidKeyAlgEnum!, $ownerId: String!, $expiresAt: String) {
  keyCreate(label: $label, alg: $alg, ownerId: $ownerId, expiresAt: $expiresAt) {
    id
    label
    algorithm
    did
    publicKeyMultibase
    createdAt
    status
  }
}

Variables: - label: Key label - alg: Algorithm (always ED25519) - ownerId: User or session identifier - expiresAt: Optional expiry date (ISO 8601)

Returns: Created key object

didBind¶

Bind a key to a did:web DID.

mutation BindDid($keyId: String!, $targetDid: String!) {
  didBind(keyId: $keyId, targetDid: $targetDid) {
    id
    did
  }
}

Variables: - keyId: Key identifier - targetDid: Target did:web DID

Returns: Updated key object

proofCreate¶

Create a data integrity proof.

mutation CreateProof($payload: String!, $keyId: String!) {
  proofCreate(payload: $payload, keyId: $keyId) {
    proof
  }
}

Variables: - payload: Document payload (JSON string) - keyId: Key identifier to use for signing

Returns: Proof object (JSON string)

Enums¶

DidKeyAlgEnum¶

• ED25519: EdDSA using Ed25519 curve

Error Handling¶

GraphQL errors are returned in the errors array:

{
  "errors": [
    {
      "message": "Error description",
      "extensions": {
        "code": "ERROR_CODE"
      }
    }
  ]
}

Common errors: - KEY_LIMIT_EXCEEDED: Too many keys for this user - USERNAME_ALREADY_EXISTS: Username already registered - NO_CREDENTIAL: No WebAuthn credential for username - INVALID_DID: Invalid DID format or unresolvable