Credential Issuer Endpoints

On this page, we’ll dive into the different credential issuer endpoints.


POST/api/v1/credentials

Issue Credential

The Create Credential API creates a verifiable credential in response to an onboarding request launched by a trading partner user. The API can be used by the Credential Issuer to provide CARO with the created credentials.

Issued credentials are revocable by default via Spherity's EthrRevocationRegistry revocation method. If you with to use the LDAP revocation method, make sure to specify the optional credentialStatusId parameter with all necessary information.

Required attributes

  • Name
    credentialType
    Type
    enum(string) / IdentityCredential OR DSCSAATPCredential OR DSCSAAuthorityCredential OR DSCSAATPEquivalentCredential
    Description

    Type of the issued credential

  • Name
    recipientDid
    Type
    string
    Description

    The DID that will receive and hold the credential`.

  • Name
    data
    Type
    json
    Description

    The json of Credential Data described down below

Optional attributes

  • Name
    credentialId
    Type
    string (urn:uuid:)
    Description

    ID of the issued credential. If left out, CARO will generate an appropriate ID.

  • Name
    credentialStatusId
    Type
    string
    Description

    CredentialStatus URL in LDAP format. If left out, EthrRevocationRegistry method will be used by default.

  • Name
    expirationDate
    Type
    string (ISO 8601 format)
    Description

    Custom expiration date (default: 1 year).

  • Name
    issuanceDate
    Type
    string (ISO 8601 format)
    Description

    Custom issuance date (default: current date).

  • Name
    onboardingId
    Type
    string
    Description

    ID of the onboarding the credential issuance originates from.

Credential Data

  • Name
    issuerName
    Type
    string
    Description

    The name of the credential issuer

  • Name
    legalName
    Type
    string
    Description

    The legal name of the organization.

  • Name
    streetAddress
    Type
    string
    Description

    The street address of the organization.

  • Name
    addressLocality
    Type
    string
    Description

    The address locality of the organization.

  • Name
    addressRegion
    Type
    string
    Description

    The address region of the organization.

  • Name
    postalCode
    Type
    string
    Description

    The postal code of the organization.

  • Name
    addressCountry
    Type
    string
    Description

    The address country of the organization.

Optional JSON for credential data

  • Name
    parentOrganization
    Type
    string
    Description

    The name of the parent organization.

  • Name
    organizationType
    Type
    string
    Description

    The name of the parent organization.

  • Name
    identifier
    Type
    string
    Description

    The identifier DID that the credential is issued to.

Request

POST
https://api.caro.vc/api/v1/credentials
{
  "credentialId" : "urn:uuid:31ec4c88-56f4-420d-a525-aba23a59af5d",
  "credentialType": "DSCSAATPCredential",
  "credentialStatusId": "ldap://example.com",
  "expirationDate": "2025-06-01T09:17:17.038Z",
  "issuanceDate": "2022-06-01T09:17:17.038Z",
  "recipientDid": "did:ethr:ropsten:0x022e41cff8e1d8c34f82397312490f96379cac8027696d8774f3eef72551691def",
  "onboardingId": "a0cedaf1-576d-4d6b-a7c6-c3859f9938b2",
  "data": {
    "issuerName": "Example Company",
    "legalName": "ABC Limited",
    "streetAddress": "Plot A, Street B, Area C",
    "addressLocality": "ABC",
    "addressRegion": "EFG",
    "postalCode": "000000",
    "addressCountry": "US",
    "parentOrganization": "Parent",
    "organizationType": "NGO",
    "identifier": "Some reasonable Identifier",
  },
}

Response

{
  "id": "780ea089-1eef-4e2a-8666-46d0b1118c59",
  "createdAt": "2022-06-01T09:17:17.038Z",
  "updatedAt": "2022-06-01T09:17:17.038Z",
  "type": "DSCSAATPCredential",
  "data": {
    "@context": [
      ...
    ],
    "id": "urn:uuid:a620a63c-8206-4825-b469-61bd660979c3",
    "type": [
      "VerifiableCredential",
      "DSCSAATPCredential"
    ],
    "issuer": "did:ethr:...",
    "issuanceDate": "2022-06-01T09:17:17.038Z",
    "expirationDate": "2023-06-01T09:17:17.038Z",
    "onboardingId": "a0cedaf1-576d-4d6b-a7c6-c3859f9938b2",
    "credentialSubject": {
      "id": "did:ethr:...",
      "type": "DSCSAATPCredential",
      "issuerName": "Example Issuer",
      "legalName": "ABC Limited",
      "streetAddress": "Plot A, Street B, Area C",
      "postalCode": "000000",
      "organizationType": "NGO",
      "addressCountry": "US",
      "addressLocality": "ABC",
      "addressRegion": "EFG",
      "identifier": "did:ethr:..."
    },
    "proof": {
      "jws": "...",
      "type": "EcdsaSecp256k1RecoverySignature2020",
      "created": "2022-06-01T09:17:17.038Z",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "did:ethr:...#controller"
    }
  }
}

Response

KeyDescription
idInternal id of the issued credential - string (uuid)
createdAtTime of credential creation - string (ISO 8601 format)
updatedAtTime of credential creation - string (ISO 8601 format)
typeCreated credential type - enum(string) / IdentityCredential OR DSCSAATPCredential OR DSCSAAuthorityCredential OR DSCSAATPEquivalentCredential
dataVerifiable credential - credential data

POST /api/v1/credentials/presentations

Create Presentation

The presentations endpoint may be used to retrieve a Verifiable Presentation for a requested credential type held by a DID. For instance, this could be used to retrieve a DID's IdentityCredential.

Required attributes

  • Name
    holderDid
    Type
    string
    Description

    DID of the holder for the requested presentation.

  • Name
    credentialType
    Type
    enum(string) | IdentityCredential OR DSCSAATPCredential OR DSCSAAuthorityCredential OR DSCSAATPEquivalentCredential
    Description

    Type of credential that a presentation is requested for.

Request

POST
https://api.caro.vc/api/v1/credentials/presentations
curl -G "https://api.caro.vc/api/v1/credentials/presentations" \
  -H "Authorization: Bearer {token}" \
  -d holderDID=""
  -d credentialType=""
{
  "verifiableCredential": [
    {
      "proof": {
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19...",
        "type": "Ed25519Signature2018",
        "created": "2022-03-17T12:30:54Z",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "did:key:z6MkicdicToW5HbxPP7zZV1H7RHvXgRMhoujWAF2n5WQkdd2#z6MkicdicToW5HbxPP7zZV1H7RHvXgRMhoujWAF2n5WQkdd2"
      },
      "id": "urn:uuid:31ec4c88-56f4-420d-a525-aba23a59af5d",
      "type": ["VerifiableCredential", "IdentityCredential"],
      "issuer": "did:key:z6MkicdicToW5HbxPP7zZV1H7RHvXgRMhoujWAF2n5WQkdd2",
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://open-credentialing-initiative.github.io/schemas/credentials/IdentityCredential-v1.0.0.jsonld",
        "https://spherity.github.io/vc-status-2021-ldap/contexts/vc-status-2021-ldap/v1.jsonld"
      ],
      "issuanceDate": "2022-03-17T12:30:54.121Z",
      "expirationDate": "2023-03-17T12:30:54.116Z",
      "credentialStatus": {
        "id": "ldaps://127.0.0.1:1111/o=urn:uuid:31ec4c88-56f4-420d-a525-aba23a59af5d,cn=CRL%20111,ou=Demo,dc=DemoIssuer,dc=com",
        "ssl": true,
        "host": "127.0.0.1:1111",
        "type": "RevocationStatus2021LDAP",
        "query": "o={{0}},cn={{1}},ou={{2}},dc={{3}}",
        "params": [
          "urn:uuid:31ec4c88-56f4-420d-a525-aba23a59af5d",
          "CRL 111",
          "Demo",
          "com"
        ]
      },
      "credentialSubject": {
        "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
        "type": "IdentityCredential",
        "legalName": "Some Name",
        "issuerName": "DemoIssuer",
        "postalCode": "001111",
        "addressRegion": "Some Region",
        "streetAddress": "Some Street",
        "addressCountry": "Some Country",
        "addressLocality": "Some Locality",
        "parentOrganization": "Some Organization"
      }
    }
  ],
  "holder": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
  "type": ["VerifiablePresentation"],
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "issuanceDate": "2022-03-17T12:30:54.000Z",
  "proof": {
    "type": "JwtProof2020",
    "jwt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
  }
}

GET /api/v1/onboardings/:id

Get Onboarding Details

The get onboarding details endpoint may be used to retrieve details for a specific onboarding uuid. This uuid may be shared with you beforehand to be used in this call.

Request

GET
https://api.caro.vc/api/v1/onboardings/gQQXg3hrtjh7AvZ
curl https://api.caro.vc/api/v1/onboardings/gQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"

Response

{
  "id":"90358ff6-8822-4588-8e51-88cb3cbc4399",
  "createdAt":"2022-02-28T16:35:14.668Z",
  "updatedAt":"2022-02-28T16:35:14.668Z",
  "identifier":{
    "did":"did:key:z6Mkvuuw4EhjssdXj3SShaSWNoEyJ1escEtj1tTnArcWCcDf"
  },
  "identifierId":"bcc557d6-349f-4f9c-af91-b28168e496e8",
  "credentialType":"IdentityCredential",
  "returnUrl":"https://example.com/",
  "userId":"12412451241421",
  "events":[
    {
      "id":"a9f6f502-b590-4972-a32a-7898b2a9870f",
      "createdAt":"2022-02-29T12:35:14.668Z",
      "status":"initiated"
    }
  ]
}

Response Body

KeyDescription
idUnique uuid of the onboarding
createdAtDate at which the ressource has been created
updatedAtDate at which the ressource has been last modified
identifierIdentifier object containing the DID used for the onboarding
identifierIdUnique id of the identifier object
credentialTypeType of requested credential
returnUrlURL which to return the user to
userIdUnique id of the user who initiated the onboarding
eventsArray of event objects which are sorted descending by creation date - Each event represents one state change in the onboarding

Identifier Object

KeyDescription
didDID used for the onboarding

Event Object

KeyDescription
idInternal id of the event
createdAtDate at which the ressource has been created
statusStatus name of the event

POST/api/v1/onboardings/:id/events

Create Onboarding Events

The create onboarding events endpoint allows you to create new 'events' related to an onboarding - An event represents a state change on an onboarding and may be used to reflect what the current state of an onboarding is.

Required attributes

  • Name
    status
    Type
    enum | string
    Description

    status of the event.

Optional attributes

  • Name
    reason
    Type
    string
    Description

    optional reason which may be specified to describe the posted status further

Request

POST
https://api.caro.vc/api/v1/onboardings/:id/events
curl -X POST https://api.caro.vc/api/v1/onboardings/:id/events \
  -H "Authorization: Bearer {token}" \
  -d 'status'= 'initiated'
  -d 'reason' = ''

GET/api/v1/revocation/credential/:credentialId/status

Get Revocation Status of a Credential

The get revocation status endpoint returns the revocation status for a provided credentialId referencing a previously issued credential with the EthrRevocationRegistry revocation method.

The revocation status can be either true or false which also allows issuers to unrevoke previously revoked credentials.

Request

GET
https://api.caro.vc/api/v1/revocation/credential/:credentialId/status
curl -X GET https://api.caro.vc/api/v1/revocation/credential/urn:uuid:a3a15c09-71de-40c8-a8c3-4c0435ffe3cb/status \
  -H "Authorization: Bearer {token}"

Response

{
  "revoked" : false
}

Response Body

KeyDescription
revokedBoolean value representing the revocation state of the requested credential

POST/v1/revocation/credential/:credentialId/changeStatus

Change Revocation Status of a Credential

The change revocation status endpoint changes the revocation status for a provided credentialId referencing a previously issued credential with the EthrRevocationRegistry revocation method.

Required attributes

  • Name
    revocationState
    Type
    enum
    Description

    The revocation state to set for the credential. Allowed enum values are REVOKED or UNREVOKED.

Request

GET
https://api.caro.vc/api/v1/revocation/credential/:credentialId/changeStatus
{
  "revocationState": "REVOKED",
}

Response

{
  "id": "038457ea-4d57-465c-99ab-95f1534d5478",
  "createdAt": "2023-06-15T08:44:12.445Z",
  "updatedAt": "2023-06-15T08:44:12.445Z",
  "status": "QUEUED",
  "error": null,
  "type": "REVOCATION",
  "chainId": 5,
  "version": 0
}

Response Body

KeyDescription
idUUID of the blockchain execution job
createdAtDate representing the creation date of the blockchain execution job
updatedAtDate representing the update date of the blockchain execution job
statusStatus of the revocation job. Possible values are QUEUED, PICKED_UP, PENDING, UNSUCCESSFUL, SUCCESSFUL
errorPossible errors when creating the blockchain execution job
typeType of the blockchain execution job. This should be REVOCATION.
chainIdNumber representing the chainId the job is being executed on. 5 is Goerli (test) and 1 is Mainnet (production)
versionNumber to keep track of already picked up actions

POST/api/v1/revocation/changeStatuses

Change Revocation Status of Multiple Credentials

The change statuses endpoint changes the revocation status for an array of provided credentialIds referencing previously issued credentials with the EthrRevocationRegistry revocation method.

Required attributes

  • Name
    revocationKeyInstructions
    Type
    array
    Description

    Array of revocation key instructions.

    • Name
      credentialId
      Type
      string
      Description

      id of the credential to be revoked

    • Name
      revocationState
      Type
      enum
      Description

      The revocation state to set for the credential. Allowed enum values are REVOKED or UNREVOKED.

Request

GET
https://api.caro.vc/api/v1/revocation/changeStatuses
{
  "revocationKeyInstructions": [
    {
      "credentialId": "urn:uuid:fc7ebaee-4bde-4e6c-852a-d69cf38765cc",
      "revocationState": "REVOKED"
    },
    {
      "credentialId": "urn:uuid:4c94b4eb-fa2c-4251-8644-f72f84214005",
      "revocationState": "REVOKED"
    },
    {
      "credentialId": "urn:uuid:24850516-5214-4fac-a003-89c2fd114e89",
      "revocationState": "UNREVOKED"
    }
  ]
}

Response

{
  "id": "418d7fd5-fcdf-4944-9e1c-1de77ba6cbc8",
  "createdAt": "2023-06-15T08:44:12.445Z",
  "updatedAt": "2023-06-15T08:44:12.445Z",
  "status": "QUEUED",
  "error": null,
  "type": "REVOCATION",
  "chainId": 5,
  "version": 0
}

Response Body

KeyDescription
idUUID of the blockchain execution job
createdAtDate representing the creation date of the blockchain execution job
updatedAtDate representing the update date of the blockchain execution job
statusStatus of the revocation job. Possible values are QUEUED, PICKED_UP, PENDING, UNSUCCESSFUL, SUCCESSFUL
errorPossible errors when creating the blockchain execution job
typeType of the blockchain execution job. This should be REVOCATION.
chainIdNumber representing the chainId the job is being executed on. 5 is Goerli (test) and 1 is Mainnet (production)
versionNumber to keep track of already picked up actions