Polygon ID Credentials API

openapi: 3.2.0
info:
  title: Privado ID - Issuer Agent Credentials API
  description: "The Issuer Node Core API is ideal for users who need multiple identities and for integrator profiles, who want to \ncreate solutions based on Privado ID functionalities and might be interested in having access to low level \ninformation such as Merkle Trees.\nThe Issuer Node API provide the following functionalities:\n* Create and retrieve Identities\n* Create a Verifiable Credential (VC)\n* Retrieve a Verifiable Credential or a list of Verifiable Credentials\n* Generate JSON to create a QR Code and use that to accept credentials in a wallet\n* Revoke a Verifiable Credential\n* Check revocation status of a Verifiable Credential\n* Retrieve the Revocation Status of a Verifiable Credential\n* Call Agent Endpoint using the Wallet App\n* Handle connections.\n"
  version: '1'
servers:
- url: https://issuer-node-core-api-testing.privado.id
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Credentials
  description: Collection of endpoints related to Credentials
paths:
  /v2/identities/{identifier}/credentials:
    post:
      summary: Create Credential
      operationId: CreateCredential
      description: Creates a credential for the provided identity.
      tags:
      - Credentials
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/pathIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCredentialRequest'
      responses:
        '201':
          description: Credential Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCredentialResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
    get:
      summary: Get Credentials
      operationId: GetCredentials
      description: 'Returns a list of credentials for the provided identity. Results are paginated.

        Filter between all | revoked | expired credentials and also perform a full text search with the query parameter.

        '
      tags:
      - Credentials
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/pathIdentifier'
      - in: query
        name: page
        schema:
          type: integer
          format: uint
          minimum: 1
          example: 1
        description: Page to fetch. First is one. If omitted, all results will be returned.
      - in: query
        name: credentialSubject
        schema:
          type: string
          example: did:polygonid:polygon:amoy:2qFpPHotk6oyaX1fcrpQFT4BMnmg8YszUwxYtaoGoe
      - in: query
        name: schemaType
        schema:
          type: string
          example: UniquenessCredential
        description: Filter credentials by schema type (partial match)
      - in: query
        name: schemaUrl
        schema:
          type: string
          example: ipfs://QmYpsAHYPrNNaNc2o9SAMrPknSAYYAbse4hYxQgMP64Tvj
        description: Filter credentials by schema URL (begins with match)
      - in: query
        name: status
        schema:
          type: string
          enum:
          - all
          - revoked
          - expired
        description: "Credential status:\n  * `all` - All Credentials. (default value)\n  * `revoked` - Only revoked credentials\n  * `expired` - Only expired credentials\n"
      - in: query
        name: query
        schema:
          type: string
        description: Query string to do full text search
      - in: query
        name: max_results
        schema:
          type: integer
          format: uint
          example: 50
          default: 50
        description: Number of items to fetch on each page. Minimum is 10. Default is 50. No maximum by the moment.
      - in: query
        name: sort
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - schemaType
            - -schemaType
            - createdAt
            - -createdAt
            - expiresAt
            - -expiresAt
            - revoked
            - -revoked
            default: -createdAt
          description: 'The minus sign (-) before createdAt means descending order.

            '
      responses:
        '200':
          description: List of credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialsPaginated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /v2/identities/{identifier}/credentials/{id}:
    get:
      summary: Get Credential
      operationId: GetCredential
      description: Get a specific credential for the provided identity.
      tags:
      - Credentials
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/pathIdentifier'
      - $ref: '#/components/parameters/pathClaim'
      responses:
        '200':
          description: Credential found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    delete:
      summary: Delete Credential
      operationId: DeleteCredential
      description: Remove a specific credential for the provided identity.
      tags:
      - Credentials
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/pathIdentifier'
      - $ref: '#/components/parameters/pathClaim'
      responses:
        '200':
          description: Credential deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericMessage'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  /v2/identities/{identifier}/credentials/revoke/{nonce}:
    post:
      summary: Revoke Credential
      operationId: RevokeCredential
      description: Revokes a specific credential for the provided identity.
      tags:
      - Credentials
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/pathIdentifier'
      - $ref: '#/components/parameters/pathNonce'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeClaimResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /v1/{identifier}/claims/revocation/status/{nonce}:
    get:
      summary: Get Revocation Status V1
      operationId: GetRevocationStatus
      deprecated: true
      description: Endpoint to get the revocation status
      tags:
      - Credentials
      parameters:
      - $ref: '#/components/parameters/pathIdentifier'
      - $ref: '#/components/parameters/pathNonce'
      responses:
        '200':
          description: Proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevocationStatusResponse'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
  /v2/identities/{identifier}/credentials/revocation/status/{nonce}:
    get:
      summary: Get Revocation Status
      operationId: GetRevocationStatusV2
      description: Endpoint to get the revocation status
      tags:
      - Credentials
      parameters:
      - $ref: '#/components/parameters/pathIdentifier'
      - $ref: '#/components/parameters/pathNonce'
      responses:
        '200':
          description: Proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevocationStatusResponse'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
  /v2/identities/{identifier}/credentials/{id}/offer:
    get:
      summary: Get Credentials Offer
      operationId: GetCredentialOffer
      description: Returns a universal/deep link to an offer or raw offer message that can be used for accepting a claim. | Response can be in 3 formats `universalLink`, `deepLink` or `raw`. Default is `universalLink`. Raw is the raw QR code and link is a QR code with a link to the raw content. Regardless of the type, the field will always be called universalLink.
      tags:
      - Credentials
      security:
      - basicAuth: []
      parameters:
      - $ref: '#/components/parameters/pathIdentifier'
      - $ref: '#/components/parameters/pathClaim'
      - name: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - universalLink
          - deepLink
          - raw
        description: "Type:\n  * `universalLink` - (default value) Returns a universal link. The preferred and more standard way to access the offer message  \n  * `deepLink` -  Returns a deeplink with a link redirection to the original message.   \n  * `raw` - Returns the raw offer message.\n"
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialOfferResponse'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
components:
  responses:
    '500':
      description: Internal Server  error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericErrorMessage'
    '409':
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericErrorMessage'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericErrorMessage'
    '422':
      description: Unprocessable Content
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericErrorMessage'
    '404':
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericErrorMessage'
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericErrorMessage'
  schemas:
    CredentialOfferResponse:
      type: object
      required:
      - universalLink
      - schemaType
      properties:
        universalLink:
          type: string
          example: https://wallet.privado.id#request_uri=https%3A%2F%2Fissuer-demo.polygonid.me%2Fapi%2Fqr-store%3Fid%3Df780a169-8959-4380-9461-f7200e2ed3f4
        schemaType:
          type: string
          example: vaccinationCertificate
    GenericErrorMessage:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: Something happen
    PaginatedMetadata:
      type: object
      required:
      - total
      - page
      - max_results
      properties:
        total:
          type: integer
          format: uint
          example: 1
        page:
          type: integer
          format: uint
          example: 1
        max_results:
          type: integer
          format: uint
          example: 50
    Credential:
      type: object
      required:
      - id
      - proofTypes
      - revoked
      - schemaHash
      properties:
        id:
          type: string
          x-omitempty: false
        proofTypes:
          type: array
          items:
            type: string
          example:
          - BJJSignature2021
        revoked:
          type: boolean
          example: false
        schemaHash:
          type: string
          example: c9b2370371b7fa8b3dab2a5ba81b6838
        vc:
          type: object
          x-go-type: verifiable.W3CCredential
          x-go-type-import:
            name: verifiable
            path: github.com/iden3/go-schema-processor/v2/verifiable
        encryptedVC:
          $ref: '#/components/schemas/EncryptedVC'
    CreateCredentialRequest:
      type: object
      required:
      - credentialSchema
      - type
      - credentialSubject
      properties:
        credentialSchema:
          type: string
          x-omitempty: false
        claimID:
          type: string
          x-go-type: uuid.UUID
          x-omitempty: false
        type:
          type: string
          x-omitempty: false
        credentialSubject:
          type: object
          x-omitempty: false
        expiration:
          type: integer
          format: int64
        version:
          type: integer
          format: uint32
        revNonce:
          type: integer
          format: uint64
        subjectPosition:
          type: string
        merklizedRootPosition:
          type: string
        refreshService:
          $ref: '#/components/schemas/RefreshService'
        displayMethod:
          $ref: '#/components/schemas/DisplayMethod'
        proofs:
          type: array
          items:
            type: string
            x-omitempty: false
            example: BJJSignature2021
            enum:
            - BJJSignature2021
            - Iden3SparseMerkleTreeProof
        credentialStatusType:
          type: string
          x-omitempty: true
          example: Iden3ReverseSparseMerkleTreeProof
          enum:
          - Iden3commRevocationStatusV1.0
          - Iden3ReverseSparseMerkleTreeProof
          - Iden3OnchainSparseMerkleTreeProof2023
        encryptionKey:
          type: object
          x-omitempty: true
          example:
            EncryptionKey:
              summary: Encryption Key
              value:
                alg: ECDH-ES+A256KW
                crv: P-256
                kid: tu-kid
                kty: EC
                use: enc
                x: 8UfTxPvmMFAPuqwtxaRWrWmihC_7uYF2rEnxa4lLQ_s
                y: M4PFcNXKyyRJ3zNPg19FlB6O0Tlbqs8euRcflpbDtcE
      example:
        credentialSchema: https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json/KYCAgeCredential-v3.json
        type: KYCAgeCredential
        credentialSubject:
          id: fill with did
          birthday: 19960424
          documentType: 2
        expiration: 1903357766
    RevokeClaimResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          x-omitempty: false
          example: pending
    RefreshService:
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: string
          x-omitempty: false
        type:
          type: string
          x-omitempty: false
          enum:
          - Iden3RefreshService2023
    RevocationStatusResponse:
      type: object
      required:
      - issuer
      - mtp
      properties:
        issuer:
          type: object
          properties:
            state:
              type: string
            rootOfRoots:
              type: string
            claimsTreeRoot:
              type: string
            revocationTreeRoot:
              type: string
        mtp:
          type: object
          required:
          - existence
          properties:
            existence:
              type: boolean
            siblings:
              type: array
              x-omitempty: false
              items:
                type: string
            node_aux:
              type: object
              properties:
                key:
                  type: string
                value:
                  type: string
    DisplayMethod:
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: string
          x-omitempty: false
        type:
          type: string
          x-omitempty: false
          enum:
          - Iden3BasicDisplayMethodV1
    CredentialsPaginated:
      type: object
      required:
      - items
      - meta
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Credential'
        meta:
          $ref: '#/components/schemas/PaginatedMetadata'
    GenericMessage:
      type: object
      required:
      - message
      properties:
        message:
          type: string
    EncryptedVC:
      type: object
      required:
      - id
      - data
      - proof
      - context
      - type
      - issuanceDate
      - credentialStatus
      properties:
        id:
          type: string
          x-omitempty: false
        data:
          type: object
          x-go-type: protocol.JWEJSONEncryption
          x-go-type-import:
            name: protocol
            path: github.com/iden3/iden3comm/v2/protocol
        proof:
          type: object
          x-go-type: verifiable.CredentialProofs
          x-go-type-import:
            name: verifiable
            path: github.com/iden3/go-schema-processor/v2/verifiable
        context:
          type: string
          example: https://www.w3.org/2018/credentials/examples/v1
        type:
          type: string
          example: KYCAgeCredential
        expirationDate:
          $ref: '#/components/schemas/TimeUTC'
        issuanceDate:
          $ref: '#/components/schemas/TimeUTC'
        credentialStatus:
          type: object
          x-go-type: verifiable.CredentialStatus
          x-go-type-import:
            name: verifiable
            path: github.com/iden3/go-schema-processor/v2/verifiable
    CreateCredentialResponse:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          x-omitempty: false
    TimeUTC:
      type: string
      x-go-type: timeapi.Time
      x-go-type-import:
        name: timeapi
        path: github.com/polygonid/sh-id-platform/internal/timeapi
      example: '2023-10-26T10:59:08Z'
      x-omitempty: false
  parameters:
    pathClaim:
      name: id
      in: path
      required: true
      description: Claim identifier
      schema:
        type: string
    pathIdentifier:
      name: identifier
      in: path
      required: true
      description: Issuer identifier
      schema:
        type: string
    pathNonce:
      name: nonce
      in: path
      required: true
      description: Claim nonce
      schema:
        type: integer
        format: int64
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic