SpruceID Credentials API

openapi: 3.0.3
info:
  title: SpruceID DIDKit HTTP Credentials 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: Credentials
  description: Issue and verify W3C Verifiable Credentials using the VC API specification. Supports both legacy (/issue/credentials, /verify/credentials) and current (/credentials/issue, /credentials/verify) path styles.
paths:
  /credentials/issue:
    post:
      summary: Issue Verifiable Credential
      description: Issues a W3C Verifiable Credential by adding a cryptographic proof. Supports Data Integrity proofs (LDP) and JSON Web Token (JWT) proof formats. The issuer DID must match a key configured in the server. Supported DID methods include did:key, did:web, did:ethr, and did:tz.
      operationId: issueCredential
      tags:
      - Credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueCredentialRequest'
            examples:
              dataIntegrityProof:
                summary: Issue with EdDSA Data Integrity Proof
                value:
                  credential:
                    '@context':
                    - https://www.w3.org/2018/credentials/v1
                    id: urn:uuid:86294362-4254-4f36-854f-3952fe42555d
                    type:
                    - VerifiableCredential
                    issuer: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
                    issuanceDate: '2020-03-16T22:37:26.544Z'
                    credentialSubject:
                      id: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
                  options:
                    proofFormat: ldp
                    verificationMethod: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b#z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
                    proofPurpose: assertionMethod
              jwtVc:
                summary: Issue as JWT-VC
                value:
                  credential:
                    '@context':
                    - https://www.w3.org/2018/credentials/v1
                    type:
                    - VerifiableCredential
                    issuer: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
                    issuanceDate: '2020-03-16T22:37:26.544Z'
                    credentialSubject:
                      id: did:example:abcdefgh
                  options:
                    proofFormat: jwt
      responses:
        '201':
          description: Verifiable Credential issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCredentialResponse'
        '400':
          description: Bad request - invalid credential or options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error - signing failure or DID resolution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /issue/credentials:
    post:
      summary: Issue Verifiable Credential (legacy path)
      description: Legacy VC HTTP API 0.0.1 path for issuing verifiable credentials. Identical functionality to POST /credentials/issue.
      operationId: issueCredentialLegacy
      tags:
      - Credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueCredentialRequest'
      responses:
        '201':
          description: Verifiable Credential issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCredentialResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/verify:
    post:
      summary: Verify Verifiable Credential
      description: Verifies a W3C Verifiable Credential by checking its cryptographic proof, credential status (if applicable), and other properties. Returns a verification result with checks performed, warnings, and errors.
      operationId: verifyCredential
      tags:
      - Credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyCredentialRequest'
            examples:
              ldpCredential:
                summary: Verify a credential with Data Integrity proof
                value:
                  verifiableCredential:
                    '@context':
                    - https://www.w3.org/2018/credentials/v1
                    - https://w3id.org/security/data-integrity/v2
                    id: urn:uuid:86294362-4254-4f36-854f-3952fe42555d
                    type:
                    - VerifiableCredential
                    issuer: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
                    issuanceDate: '2020-03-16T22:37:26.544Z'
                    credentialSubject:
                      id: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
                    proof:
                      type: DataIntegrityProof
                      cryptosuite: eddsa-rdfc-2022
                      created: '2024-11-05T19:11:37Z'
                      verificationMethod: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b#z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
                      proofPurpose: assertionMethod
                      proofValue: z4WrjAqrwg92y1RR8S63rav...
                  options: {}
      responses:
        '200':
          description: Verification result returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /verify/credentials:
    post:
      summary: Verify Verifiable Credential (legacy path)
      description: Legacy VC HTTP API 0.0.1 path for verifying verifiable credentials. Identical functionality to POST /credentials/verify.
      operationId: verifyCredentialLegacy
      tags:
      - Credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyCredentialRequest'
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    VerificationOptions:
      type: object
      description: Options for verification operations
      properties:
        proofPurpose:
          type: string
          description: Expected proof purpose
          enum:
          - assertionMethod
          - authentication
          - keyAgreement
          - capabilityInvocation
          - capabilityDelegation
        verificationMethod:
          type: string
          description: Expected verification method DID URL
    VerifiableCredential:
      type: object
      description: A W3C Verifiable Credential (VC Data Model 1.1 or 2.0). May be represented as a JSON-LD credential with a linked data proof, or as a JWT string.
      required:
      - '@context'
      - type
      - issuer
      - credentialSubject
      properties:
        '@context':
          oneOf:
          - type: string
          - type: array
            items:
              oneOf:
              - type: string
              - type: object
          description: JSON-LD context(s) for the credential
          example:
          - https://www.w3.org/2018/credentials/v1
        id:
          type: string
          format: uri
          description: Unique identifier for the credential
          example: urn:uuid:86294362-4254-4f36-854f-3952fe42555d
        type:
          type: array
          items:
            type: string
          description: Credential type(s), must include VerifiableCredential
          example:
          - VerifiableCredential
        issuer:
          oneOf:
          - type: string
            description: DID of the issuer
          - type: object
            description: Issuer object with id and optional metadata
            properties:
              id:
                type: string
          example: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
        issuanceDate:
          type: string
          format: date-time
          description: Date and time the credential was issued (VC 1.1)
          example: '2020-03-16T22:37:26.544Z'
        validFrom:
          type: string
          format: date-time
          description: Date from which the credential is valid (VC 2.0)
        expirationDate:
          type: string
          format: date-time
          description: Expiration date of the credential (VC 1.1)
        credentialSubject:
          oneOf:
          - type: object
          - type: array
            items:
              type: object
          description: The subject(s) of the credential
        credentialStatus:
          type: object
          description: Credential status (e.g. BitstringStatusListEntry for revocation)
          properties:
            id:
              type: string
            type:
              type: string
        proof:
          oneOf:
          - $ref: '#/components/schemas/DataIntegrityProof'
          - type: array
            items:
              $ref: '#/components/schemas/DataIntegrityProof'
          description: Cryptographic proof(s) on the credential
    Error:
      type: object
      description: Error response
      properties:
        error:
          type: string
          description: Error message
        message:
          type: string
          description: Detailed error description
    IssueCredentialRequest:
      type: object
      required:
      - credential
      - options
      properties:
        credential:
          $ref: '#/components/schemas/VerifiableCredential'
        options:
          $ref: '#/components/schemas/JWTOrLDPOptions'
    VerifyCredentialRequest:
      type: object
      required:
      - verifiableCredential
      properties:
        verifiableCredential:
          oneOf:
          - $ref: '#/components/schemas/VerifiableCredential'
          - type: string
            description: JWT-encoded verifiable credential
        options:
          $ref: '#/components/schemas/VerificationOptions'
    VerificationResult:
      type: object
      description: Summary of verification checks performed on a credential or presentation. Based on the W3C VC HTTP API VerificationResult schema.
      properties:
        checks:
          type: array
          description: The checks that were performed
          items:
            type: string
            enum:
            - proof
            - JWS
            - status
          example:
          - proof
        warnings:
          type: array
          description: Non-fatal warnings encountered during verification
          items:
            type: string
          example: []
        errors:
          type: array
          description: Errors encountered during verification (empty means success)
          items:
            type: string
          example: []
    JWTOrLDPOptions:
      type: object
      description: Combined options for credential/presentation operations. Controls whether to produce a JWT or Linked Data Proof format.
      properties:
        proofFormat:
          type: string
          description: The proof format to use
          enum:
          - ldp
          - jwt
          default: ldp
          example: ldp
        verificationMethod:
          type: string
          description: DID URL of the verification method to use for signing
          example: did:key:z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b#z6MktKwz7Ge1Yxzr4JHavN33wiwa8y81QdcMRLXQsrH9T53b
        proofPurpose:
          type: string
          description: The proof purpose for the signature
          enum:
          - assertionMethod
          - authentication
          - keyAgreement
          - capabilityInvocation
          - capabilityDelegation
          example: assertionMethod
        cryptosuite:
          type: string
          description: The cryptographic suite (for ldp format)
          example: eddsa-rdfc-2022
    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)
    IssueCredentialResponse:
      type: object
      description: A verifiable credential with proof added. If proofFormat was "jwt", this will contain a JWT string in the verifiableCredential field.
      properties:
        verifiableCredential:
          oneOf:
          - $ref: '#/components/schemas/VerifiableCredential'
          - type: string
            description: JWT-encoded verifiable credential
externalDocs:
  description: SpruceID DIDKit Documentation
  url: https://spruceid.dev/docs/didkit/