Credential Issuer Endpoints

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

Authentication

Please see Authentication for a detailed description of how to authenticate yourself with our API.

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.
If type is IdentityCredential
Name
organizationType
Type
string
Description
The name of the parent organization.
If type is DSCSAATPCredential or DSCSAATPEquivalentCredential
Name
identifier
Type
string
Description
The identifier DID that the credential is issued to.
If type is DSCSAATPCredential or DSCSAATPEquivalentCredential or DSCSAAuthorityCredential

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

Key	Description
`id`	Internal id of the issued credential - `string (uuid)`
`createdAt`	Time of credential creation - `string (ISO 8601 format)`
`updatedAt`	Time of credential creation - `string (ISO 8601 format)`
`type`	Created credential type - `enum(string) / IdentityCredential OR DSCSAATPCredential OR DSCSAAuthorityCredential OR DSCSAATPEquivalentCredential`
`data`	Verifiable 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

Key	Description
`id`	Unique uuid of the onboarding
`createdAt`	Date at which the ressource has been created
`updatedAt`	Date at which the ressource has been last modified
`identifier`	Identifier object containing the DID used for the onboarding
`identifierId`	Unique id of the identifier object
`credentialType`	Type of requested credential
`returnUrl`	URL which to return the user to
`userId`	Unique id of the user who initiated the onboarding
`events`	Array of event objects which are sorted descending by creation date - Each event represents one state change in the onboarding

Identifier Object

Key	Description
`did`	DID used for the onboarding

Event Object

Key	Description
`id`	Internal id of the event
`createdAt`	Date at which the ressource has been created
`status`	Status 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.
status possible enum values
initiated data_submitted review_pending data_incomplete credential_issued revocation_notice declined aborted

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.

credentialId Usage

You can either use the id inside of the credential (e.g.: urn:uuid:a3a15c09-71de-40c8-a8c3-4c0435ffe3cb) or the CARO specific credential id found within CARO.

Execution Time

Please note that it can take up to 2 minutes for the revocation status to be updated after a revocation action has been performed.

We will provide additional API endpoints to track revocation actions in the future.

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

Key	Description
`revoked`	Boolean 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.

credentialId Usage

You can either use the id inside of the credential (e.g.: urn:uuid:a3a15c09-71de-40c8-a8c3-4c0435ffe3cb) or the CARO specific credential id found within CARO.

Batching Revocations

Please use the change revocation status of multiple credentials whenever possible to batch revocation actions. Only use this endpoint if you need to revoke a single credential.

Execution Time

Please note that the revocation status change is not reflected immediately but may take up to 2 minutes to be anchored on the Ethereum chain.

We will provide additional API endpoints to track revocation actions in the future.

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

Key	Description
`id`	UUID of the blockchain execution job
`createdAt`	Date representing the creation date of the blockchain execution job
`updatedAt`	Date representing the update date of the blockchain execution job
`status`	Status of the revocation job. Possible values are `QUEUED`, `PICKED_UP`, `PENDING`, `UNSUCCESSFUL`, `SUCCESSFUL`
`error`	Possible errors when creating the blockchain execution job
`type`	Type of the blockchain execution job. This should be `REVOCATION`.
`chainId`	Number representing the chainId the job is being executed on. `5` is Goerli (test) and `1` is Mainnet (production)
`version`	Number 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.

credentialId Usage

You can either use the id inside of the credential (e.g.: urn:uuid:a3a15c09-71de-40c8-a8c3-4c0435ffe3cb) or the CARO specific credential id found within CARO.

Execution Time

Please note that the revocation status change is not reflected immediately but may take up to 2 minutes to be anchored on the Ethereum chain.

We will provide additional API endpoints to track revocation actions in the future.

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

Key	Description
`id`	UUID of the blockchain execution job
`createdAt`	Date representing the creation date of the blockchain execution job
`updatedAt`	Date representing the update date of the blockchain execution job
`status`	Status of the revocation job. Possible values are `QUEUED`, `PICKED_UP`, `PENDING`, `UNSUCCESSFUL`, `SUCCESSFUL`
`error`	Possible errors when creating the blockchain execution job
`type`	Type of the blockchain execution job. This should be `REVOCATION`.
`chainId`	Number representing the chainId the job is being executed on. `5` is Goerli (test) and `1` is Mainnet (production)
`version`	Number to keep track of already picked up actions