openapi: 3.0.3
info:
  title: SpruceID DIDKit HTTP Credentials Status API
  description: DIDKit is SpruceID's cross-platform toolkit for working with W3C Decentralized Identifiers (DIDs) and Verifiable Credentials (VCs). The DIDKit HTTP server exposes REST endpoints for issuing, presenting, and verifying verifiable credentials and verifiable presentations using standard cryptographic proofs. It implements the W3C VC API specification and supports multiple DID methods including did:key, did:web, did:ethr, and did:tz. DIDKit HTTP does not include built-in authorization and should be deployed behind a reverse proxy in production.
  version: 1.0.0
  contact:
    name: SpruceID Developer Support
    email: hello@spruceid.com
    url: https://spruceid.dev/docs/didkit/
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-logo:
    url: https://spruceid.com/favicon.ico
servers:
- url: http://localhost:8080
  description: Local DIDKit HTTP server instance
tags:
- name: Status
  description: Bitstring Status List credential endpoint for credential revocation status.
paths:
  /statuslist:
    get:
      summary: Get Bitstring Status List Credential
      description: Returns a W3C Bitstring Status List verifiable credential that can be used to check the revocation status of credentials issued by this server. The status list encodes credential status as a compressed bitstring. Each credential references a position in this list via a BitstringStatusListEntry credentialStatus property.
      operationId: getStatusList
      tags:
      - Status
      responses:
        '200':
          description: Bitstring Status List Verifiable Credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BitstringStatusListCredential'
        '500':
          description: Internal server error - missing signing key or configuration error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DataIntegrityProof:
      type: object
      description: A W3C Data Integrity cryptographic proof
      properties:
        type:
          type: string
          description: Proof type (e.g. DataIntegrityProof, Ed25519Signature2020)
          example: DataIntegrityProof
        cryptosuite:
          type: string
          description: The cryptographic suite used
          example: eddsa-rdfc-2022
        created:
          type: string
          format: date-time
          description: When the proof was created
          example: '2024-11-05T19:11:37Z'
        verificationMethod:
          type: string
          description: DID URL of the verification method
          example: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b#z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
        proofPurpose:
          type: string
          description: The purpose of this proof
          example: assertionMethod
        proofValue:
          type: string
          description: The base58-btc encoded proof value
          example: z4WrjAqrwg92y1RR8S63rav19ZmYWx6Vs1HBcPJgXnCiEfef4i1NqKG7jMyM2DtNdMXvACudKcra92VPxW9hfatbZ
        previousProof:
          type: string
          description: ID of a previous proof this proof covers (for multi-proof chaining)
        id:
          type: string
          description: Optional identifier for this proof (for multi-proof referencing)
    BitstringStatusListCredential:
      type: object
      description: A W3C Bitstring Status List verifiable credential for checking revocation status of other credentials.
      properties:
        '@context':
          type: array
          items:
            type: string
          example:
          - https://www.w3.org/2018/credentials/v1
          - https://www.w3.org/ns/credentials/status/v1
        id:
          type: string
          example: http://localhost:8080/statuslist
        type:
          type: array
          items:
            type: string
          example:
          - VerifiableCredential
          - BitstringStatusListCredential
        issuer:
          type: string
          example: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
        credentialSubject:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
              example: BitstringStatusList
            statusPurpose:
              type: string
              enum:
              - revocation
              - suspension
              example: revocation
            encodedList:
              type: string
              description: Base64url-encoded compressed bitstring
        proof:
          $ref: '#/components/schemas/DataIntegrityProof'
    Error:
      type: object
      description: Error response
      properties:
        error:
          type: string
          description: Error message
        message:
          type: string
          description: Detailed error description
externalDocs:
  description: SpruceID DIDKit Documentation
  url: https://spruceid.dev/docs/didkit/