Verifiable credentials admin API
The Microsoft Entra Verified ID Admin API enables you to manage all aspects of the Verifiable Credential service. It offers a way to set up a brand new service, manage and create Verifiable Credential contracts, revoke Verifiable Credentials and completely opt out the service as well.
The API is intended for developers comfortable with RESTful APIs and enough permissions on the Microsoft Entra tenant to enable the service
Base URL
The Admin API is server over HTTPS. All URLs referenced in the documentation have the following base: https://verifiedid.did.msidentity.com.
Authentication
The API is protected through Microsoft Entra ID and uses OAuth2 bearer tokens. The access token can be for a user or for an application.
User bearer tokens
The app registration needs to have the API Permission for Verifiable Credentials Service Admin and then when acquiring the access token the app should use scope 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access. The access token must be for a user with the global administrator or the authentication policy administrator role. A user with role global reader can perform read-only API calls.
Application bearer tokens
The Verifiable Credentials Service Admin service supports the following application permissions.
| Permission | Description |
|---|---|
| VerifiableCredential.Authority.ReadWrite | Permission to read/write authority object(s) |
| VerifiableCredential.Contract.ReadWrite | Permission to read/write contract object(s) |
| VerifiableCredential.Credential.Search | Permission to search for a credential to revoke |
| VerifiableCredential.Credential.Revoke | Permission to revoke a previously issued credential |
| VerifiableCredential.Network.Read | Permission to read entries from the Verified ID Network |
The app registration needs to have the API Permission for Verifiable Credentials Service Admin and permissions required from the above table. When acquiring the access token, via the client credentials flow, the app should use scope 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default.
If the app intends to create a new authority, it needs two things. First, the app registration needs the VerifiableCredential.Authority.ReadWrite permission. Second, the app needs have Create Key permission in Key Vaults Access Policies. If the app only read/writes existing authorities, it does not need the Key Vault permission.
Onboarding
This API is to help create a new environment so new authorities can be set up. This can be triggered manually by navigating to the Verifiable Credential page in the Azure portal as well. You only need to call this API once and only if you want to set up a brand new environment just with the API.
HTTP request
POST /v1.0/verifiableCredentials/onboard
Use this endpoint to finish provisioning of the Verifiable Credential service in your tenant. The system creates the rest of the service principals if these aren't provisioned yet.
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method.
Return message
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "f5bf2fc6-7135-4d94-a6fe-c26e4543bc5a",
"verifiableCredentialServicePrincipalId": "90e10a26-94cd-49d6-8cd7-cacb10f00686",
"verifiableCredentialRequestServicePrincipalId": "870e10a26-94cd-49d6-8cd7-cacb10f00fe",
"verifiableCredentialAdminServicePrincipalId": "760e10a26-94cd-49d6-8cd7-cacb10f00ab",
"status": "Enabled"
}
Repeatedly calling this API results in the exact same return message.
Authorities
This endpoint can be used to create or update a Verifiable Credential service instance.
Methods
| Methods | Return Type | Description |
|---|---|---|
| Get Authority | Authority | Read properties of an authority |
| List Authority | Authority array | Get a list of all configured Authorities/verifiable credential services |
| Create Authority | Authority | Create a new authority |
| Update authority | Authority | Update authority |
| Delete authority | Authority | Delete authority |
| Generate Well known DID Configuration | ||
| Generate DID Document | ||
| Validate Well-known DID config | ||
| Rotate Signing Key | Authority | Rotate signing key |
| Synchronize with DID Document | Authority | Synchronize DID document with new signing key |
Get authority
Retrieve the properties of a configured authority or verifiable credential service instance.
HTTP request
GET /v1.0/verifiableCredentials/authorities/:authorityId
Replace the :authorityId with the value of one of the configured authorities.
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method
Response message
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ffea7eb3-0000-1111-2222-000000000000",
"name": "ExampleAuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
The response contains the following properties.
Authority type
| Property | Type | Description |
|---|---|---|
Id |
string | An autogenerated unique ID, which can be used to retrieve or update the specific instance of the verifiable credential service |
name |
string | The friendly name of this instance of the verifiable credential service |
status |
string | status of the service, this value will always be enabled |
| didModel | didModel | Information about the DID and keys |
| keyVaultMetadata | keyVaultMeta data | Information about the used Key Vault |
didModel type
Web
| Property | Type | Description |
|---|---|---|
did |
string | The DID for this verifiable credential service instance |
signingKeys |
string array | URL to the signing key |
linkedDomainUrls |
string array | Domains linked to this DID, expecting one single entry |
| didModel | didModel | Information about the DID and keys |
didDocumentStatus |
string | status of the DID, value is always published for this method |
keyVaultMetadata type
| Property | Type | Description |
|---|---|---|
subscriptionId |
string | The Azure subscription this Key Vault resides |
resourceGroup |
string | name of the resource group from this Key Vault |
resourceName |
string | Key Vault name |
resourceUrl |
string | URL to this Key Vault |
List authorities
Get all configured authorities or verifiable credential services for this tenant
HTTP request
GET /v1.0/verifiableCredentials/authorities
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method.
Response message
Response message is an array of Authorities Example:
HTTP/1.1 200 OK
Content-type: application/json
{
value:
[
{
"id": "ffea7eb3-0000-1111-2222-000000000000",
"name": "AuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
},
{
"id": "cc55ba22-0000-1111-2222-000000000000",
"name": "AuthorityName2",
"keyVaultUrl": "https://vccontosokv.vault.azure.net/",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid2.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid2.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
]
}
Create authority
This call creates a new private key, recovery key and update key, stores these keys in the specified Azure Key Vault and sets the permissions to this Key Vault for the verifiable credential service and a create new DID with corresponding DID Document.
HTTP request
POST /v1.0/verifiableCredentials/authorities
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
In the request body, supply a JSON representation of the following
| Property | Type | Description |
|---|---|---|
name |
string | The display name of this instance of the service |
linkedDomainUrl |
string | The domain linked to this DID |
didMethod |
string | Must be web |
keyVaultMetadata |
keyVaultMetadata | meta data for specific key vault |
Example message:
{
"name":"ExampleName",
"linkedDomainUrl":"https://verifiedid.contoso.com/",
"didMethod": "web",
"keyVaultMetadata":
{
"subscriptionId":"b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup":"verifiablecredentials",
"resourceName":"vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
Response message
When successful the response message contains the name of the authority
Example message for did:web:
{
"id": "bacf5333-d68c-01c5-152b-8c9039fbd88d",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
Example message for did:ion:
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "cc55ba22-0000-1111-2222-000000000000",
"name": "APItest6",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "submitted"
},
"keyVaultMetadata": {
"subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
Remarks
You can create multiple authorities with their own DID and private keys, these will not be visible in the UI of the Azure portal. Currently we only support having 1 authority. We have not fully tested all scenarios with multiple created authorities. If you are trying this please let us know your experience.
Update authority
This method can be used to update the display name of this specific instance of the verifiable credential service.
HTTP request
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Replace the value of :authorityId with the value of the authority ID you want to update.
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
In the request body, supply a JSON representation of the following.
| Property | Type | Description |
|---|---|---|
name |
string | The display name of this instance of the service |
Example message
{
"name":"ExampleIssuerName"
}
Delete authority
This method can be used to delete an authority. Currently only did:ion authorities can be deleted. When you delete an authority, any issued Verified ID credentials becomes invalid and cannot be verified anymore as the issuing authority is gone.
HTTP request
DELETE /beta/verifiableCredentials/authorities/:authorityId
Replace the value of :authorityId with the value of the authority ID you want to delete.
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
No request body
Response message
Example response message:
Successful delete authority response.
HTTP/1.1 200 OK
If delete of authority was successful but cleanup of Azure Key Vault keys had failed, you get the below response.
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"error": {
"code": "deleteIssuerSuccessfulButKeyDeletionFailed",
"message": "The organization has been opted out of the Verifiable Credentials, but the following keys could not be deleted. To keep your organization secure, delete keys that are not in use. https://kxxxxxx.vault.azure.net/keys/vcSigningKey-9daeexxxxx-0575-23dc-81be-5f6axxxxx/0dcc532adb9a4fcf9902f90xxxxx"
}
}
Well-known DID configuration
The generateWellknownDidConfiguration method generates the signed did-configuration.json file. The file must be uploaded to the .well-known folder in the root of the website hosted for the domain in the linked domain of this verifiable credential instance. Instructions can be found here.
HTTP request
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
You need to specify one of the domains in the linkedDomains of the specified authority.
{
"domainUrl":"https://atest/"
}
Response message
Example response message:
HTTP/1.1 200 OK
Content-type: application/json
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbGciOiJFUzI1NksiL...<SNIP>..."
]
}
Save this result with the file name did-configuration.json and upload this file to the correct folder and website. If you specify a domain not linked to this DID/DID Document, you receive an error:
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"requestId":"079192a95fbf56a661c1b2dd0e012af5",
"date":"Mon, 07 Feb 2022 18:55:53 GMT",
"mscv":"AVQh55YiU3FxMipB.0",
"error":
{
"code":"wellKnownConfigDomainDoesNotExistInIssuer",
"message":"The domain used as an input to generate the well-known document is not registered with your organization. Domain: https://wrongdomain/"
}
}
Remarks
You can point multiple DIDs to the same domain. If you choose this configuration, you need to combine generated tokens and put them in the same did-configuration.json file. The file contains an array of these tokens.
For example:
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
Generate DID document
This call generates the DID Document used for DID:WEB identifiers. After generating this DID Document, the administrator has to place the file at the https://domain/.well-known/did.json location.
HTTP request
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method.
Response message
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "did:web:verifiedid.contoso.com",
"@context": [
"https://www.w3.org/ns/did/v1",
{
"@base": "did:web:verifiedid.contoso.com"
}
],
"service": [
{
"id": "#linkeddomains",
"type": "LinkedDomains",
"serviceEndpoint": {
"origins": [
"https://verifiedid.contoso.com/"
]
}
},
{
"id": "#hub",
"type": "IdentityHub",
"serviceEndpoint": {
"instances": [
"https://verifiedid.hub.msidentity.com/v1.0/f640a374-b380-42c9-8e14-d174506838e9"
]
}
}
],
"verificationMethod": [
{
"id": "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b",
"controller": "did:web:verifiedid.contoso.com",
"type": "EcdsaSecp256k1VerificationKey2019",
"publicKeyJwk": {
"crv": "secp256k1",
"kty": "EC",
"x": "bFkOsjDB_K-hfz-c-ggspVHETMeZm31CtuzOt0PrmZc",
"y": "sewHrUNpXvJ7k-_4K8Yq78KgKzT1Vb7kmhK8x7_6h0g"
}
}
],
"authentication": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
],
"assertionMethod": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
]
}
Remark
Requires the caller to have the KEY List permissions on the target key vault.
Validate well-known DID configuration
This call checks your DID setup. It downloads the well known DID configuration and validates if the correct DID is used and the signature is correct.
HTTP request
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method.
Response message
HTTP/1.1 204 No Content
Content-type: application/json
Rotate signing key
The rotate signing key creates a new private key for the did:web authority. The DID document should be re-registered to reflect the update. When this is done, the synchronizeWithDidDocument tells the system to start using the new key for signing.
HTTP request
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request Body
Don't supply a request body for this method.
Response message
The didDocumentStatus will change to outOfSync.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "bacf5333-d68c-01c5-152b-8c9039fbd88d",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "outOfSync"
},
"keyVaultMetadata": {
"subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
Synchronize with DID Document
After rotating the signing key, the DID document should be re-registered to reflect the update. When this is done, the synchronizeWithDidDocument tells the system to start using the new key for signing.
HTTP request
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request Body
Don't supply a request body for this method.
Response message
The didDocumentStatus will change from outOfSync to published on a successful call.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "bacf5333-d68c-01c5-152b-8c9039fbd88d",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
Contracts
This endpoint allows you to create new contracts, and update existing contracts. Contracts consist of two parts represented by two JSON definitions. Information on how to design and create a contract manually can be found here.
- The display definition is used by administrators to control the appearance of a verifiable credential, for example background color, logo and title of the verifiable credential. This file also contains the claims that need to be stored inside the verifiable credential.
- The rules definition contains the information on how to gather and collect attestations like self-attested claims, another verifiable credential as input or perhaps an ID Token received after a user has signed in to an OIDC compatible identity provider.
Methods
| Methods | Return Type | Description |
|---|---|---|
| Get contract | Contract | Read properties of a Contract |
| List contracts | Contract collection | Get a list of all configured contracts |
| Create contract | Contract | Create a new contract |
| Update contract | Contract | Update contract |
Get contract
HTTP request
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
Replace the :authorityId and :contractId with the correct value of the authority and contract.
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method.
Response message
example message:
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": false,
"manifestUrl": "...",
"issueNotificationAllowedToGroupOids" : null,
"rules": <rulesModel>,
"displays": <displayModel[]>,
"allowOverrideValidityIntervalOnIssuance": false
}
The response contains the following properties
Contract type
| Property | Type | Description |
|---|---|---|
Id |
string | contract ID |
name |
string | The friendly name of this contract |
status |
string | Always Enabled |
manifestUrl |
string | URL to the contract used in the issuance request |
issueNotificationEnabled |
boolean | set to true if users will be notified this VC is ready for them to get issued |
issueNotificationAllowedToGroupOids |
array of groupId strings | array of group IDs this credential will be offered to |
availableInVcDirectory |
boolean | Is this contract published in the Verifiable Credential Network |
| rules | rulesModel | rules definition |
| displays | displayModel array | display definitions |
allowOverrideValidityIntervalOnIssuance |
boolean | If the createIssuanceRequest API call is allowed to override expiry of the credential. This is only valid for idTokenHint flows. |
rulesModel type
| Property | Type | Description |
|---|---|---|
attestations |
attestations | describing supported inputs for the rules |
validityInterval |
number | this value shows the lifespan of the credential |
vc |
vcType array | types for this contract |
customStatusEndpoint |
[customStatusEndpoint] (#customstatusendpoint-type) (optional) | status endpoint to include in the verifiable credential for this contract |
If the property customStatusEndpoint property isn't specified, then the anonymous status endpoint is used.
attestations type
| Property | Type | Description |
|---|---|---|
idTokens |
idTokenAttestation (array) (optional) | describes ID token inputs |
idTokenHints |
idTokenHintAttestation (array) (optional) | describes ID token hint inputs |
presentations |
verifiablePresentationAttestation (array) (optional) | describes verifiable presentations inputs |
selfIssued |
selfIssuedAttestation (array) (optional) | describes self issued inputs |
accessTokens |
accessTokenAttestation (array) (optional) | describes access token inputs |
idTokenAttestation type
| Property | Type | Description |
|---|---|---|
mapping |
claimMapping (optional) | rules to map input claims into output claims in the verifiable credential |
configuration |
string (url) | location of the identity provider's configuration document |
clientId |
string | client ID to use when obtaining the ID token |
redirectUri |
string | redirect uri to use when obtaining the ID token MUST BE vcclient://openid/ |
scope |
string | space delimited list of scopes to use when obtaining the ID token |
required |
boolean (default false) | indicating whether this attestation is required or not |
idTokenHintAttestation type
| Property | Type | Description |
|---|---|---|
mapping |
claimMapping (optional) | rules to map input claims into output claims in the verifiable credential |
required |
boolean (default false) | indicating whether this attestation is required or not |
trustedIssuers |
string (array) | a list of DIDs allowed to issue the verifiable credential for this contract |
verifiablePresentationAttestation type
| Property | Type | Description |
|---|---|---|
mapping |
claimMapping (optional) | rules to map input claims into output claims in the verifiable credential |
credentialType |
string (optional) | required credential type of the input |
required |
boolean (default false) | indicating whether this attestation is required or not |
trustedIssuers |
string (array) | a list of DIDs allowed to issue the verifiable credential for this contract |
selfIssuedAttestation type
| Property | Type | Description |
|---|---|---|
mapping |
claimMapping (optional) | rules to map input claims into output claims in the verifiable credential |
required |
boolean (default false) | indicating whether this attestation is required or not |
accessTokenAttestation type
| Property | Type | Description |
|---|---|---|
mapping |
claimMapping (optional) | rules to map input claims into output claims in the verifiable credential |
required |
boolean (default false) | indicating whether this attestation is required or not |
Supported
inputClaimvalues for themappingsproperty are:givenName,displayName,preferredLanguage,userPrincipalName,surname,jobTitle,photo.
claimMapping type
| Property | Type | Description |
|---|---|---|
inputClaim |
string | the name of the claim to use from the input |
outputClaim |
string | the name of the claim in the verifiable credential |
indexed |
boolean (default false) | indicating whether the value of this claim is used for searching; only one clientMapping object is allowed to be indexed for a given contract |
required |
boolean (default false) | indicating whether this mapping is required or not |
type |
string (optional) | type of claim |
customStatusEndpoint type
| Property | Type | Description |
|---|---|---|
url |
string (url) | the url of the custom status endpoint |
type |
string | the type of the endpoint |
example:
"rules": {
"attestations": {
"idTokens": [
{
"clientId": "2f670d73-624a-41fe-a139-6f1f8f2d2e47",
"configuration": "https://bankofwoodgrove.b2clogin.com/bankofwoodgrove.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_si",
"redirectUri": "vcclient://openid/",
"scope": "openid",
"mapping": [
{
"outputClaim": "givenName",
"required": false,
"inputClaim": "given_name",
"indexed": false
},
{
"outputClaim": "familyName",
"required": false,
"inputClaim": "family_name",
"indexed": true
}
],
"required": false
}
]
},
"validityInterval": 2592000,
"vc": {
"type": [
"BankofWoodgroveIdentity"
]
}
}
displayModel type
| Property | Type | Description |
|---|---|---|
locale |
string | the locale of this display |
credential |
displayCredential | the display properties of the verifiable credential |
consent |
displayConsent | supplemental data when the verifiable credential is issued |
claims |
displayClaims array | labels for the claims included in the verifiable credential |
displayCredential type
| Property | Type | Description |
|---|---|---|
title |
string | title of the credential |
issuedBy |
string | the name of the issuer of the credential |
backgroundColor |
number (hex) | background color of the credential in hex, for example, #FFAABB |
textColor |
number (hex) | text color of the credential in hex, for example, #FFAABB |
description |
string | supplemental text displayed alongside each credential |
logo |
displayCredentialLogo | the logo to use for the credential |
displayCredentialLogo type
| Property | Type | Description |
|---|---|---|
uri |
string (uri) | uri of the logo. If this is a URL, it must be reachable over the public internet anonymously. |
description |
string | the description of the logo |
displayConsent type
| Property | Type | Description |
|---|---|---|
title |
string | title of the consent |
instructions |
string | supplemental text to use when displaying consent |
displayClaims type
| Property | Type | Description |
|---|---|---|
label |
string | the label of the claim in display |
claim |
string | the name of the claim to which the label applies |
type |
string | the type of the claim |
description |
string (optional) | the description of the claim |
example:
{
"displays": [
{
"locale": "en-US",
"card": {
"backgroundColor": "#FFA500",
"description": "ThisisyourBankofWoodgroveIdentity",
"issuedBy": "BankofWoodgrove",
"textColor": "#FFFF00",
"title": "BankofWoodgroveIdentity",
"logo": {
"description": "Defaultbankofwoodgrovelogo",
"uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png"
}
},
"consent": {
"instructions": "Please login with your bankofWoodgrove account to receive this credential.",
"title": "Do you want to accept the verifiedbankofWoodgrove Identity?"
},
"claims": [
{
"claim": "vc.credentialSubject.givenName",
"label": "Name",
"type": "String"
},
{
"claim": "vc.credentialSubject.familyName",
"label": "Surname",
"type": "String"
}
]
}
]
}
List contracts
This API lists all contracts configured in the current tenant for the specified authority.
HTTP request
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method.
Response message
example message:
{
"value":
[
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "test1",
"authorityId": "ffea7eb3-0000-1111-2222-000000000000",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
},
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDI",
"name": "test2",
"authorityId": "cc55ba22-0000-1111-2222-000000000000",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
}
]
}
Create contract
When creating a contract the name has to be unique in the tenant. In case you have created multiple authorities, the contract name has to be unique across all authorities. The name of the contract will be part of the contract URL, which is used in the issuance requests.
HTTP request
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Example request
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Response message
Example message:
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "GUID",
"name": "ExampleContractName1",
"issuerId": "cc55ba22-0000-1111-2222-000000000000",
"status": "Enabled",
"issueNotificationEnabled": false,
"rules": "<rules JSON>",
"displays": [{<display JSON}],
"manifestUrl": "https://..."
}
Update contract
This API Allows you to update the contract.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
Example request:
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
Response message
Example message:
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": true,
"manifestUrl": "https://...",
"issueNotificationAllowedToGroupOids" : null,
"rules": rulesModel,
"displays": displayModel[],
"allowOverrideValidityIntervalOnIssuance": true
}
Credentials
This endpoint allows you to search for issued verifiable credentials, check revocation status and revoke credentials.
Methods
| Methods | Return Type | Description |
|---|---|---|
| Get credential | Credential | Read properties of a Credential |
| Search credentials | Credential collection | Search a list of credentials with a specific claim value |
| Revoke credential | Revoke specific credential |
Get credential
This API allows you to retrieve a specific credential and check the status to see if it is revoked or not.
HTTP Request
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Response message
Example message
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
Search credentials
You are able to search for verifiable credentials with specific index claims. Since only a hash is stored, you need to search for the specific calculated value. The algorithm you need to use is: Base64Encode(SHA256(contractid + claim value)) An example in C# looks like this:
string claimvalue = "Bowen";
string contractid = "<...your-contract-id-value...>";
string output;
using (var sha256 = SHA256.Create())
{
var input = contractid + claimvalue;
byte[] inputasbytes = Encoding.UTF8.GetBytes(input);
hashedsearchclaimvalue = Convert.ToBase64String(sha256.ComputeHash(inputasbytes));
output = System.Net.WebUtility.UrlEncode( hashedsearchclaimvalue );
}
The following request shows how to add the calculated value to the filter parameter of the request. At this moment only the filter=indexclaimhash eq format is supported.
HTTP request
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method.
Response message
Example message
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"status": "valid",
"issuedAtTimestamp": "Sat, 5 Feb 2022 03:51:29 GMT"
}
]
}
Revoke credential
This API allows you to revoke a specific credential, after you searched for the credential by using the search API the credential can be revoked by specifying the specific credential ID.
HTTP request
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method.
Response message
HTTP/1.1 204 No Content
Content-type: application/json
Opt-out
This method will completely remove all instances of the verifiable credential service in this tenant. It removes all configured contracts. Every issued verifiable credential can't be checked for revocation. This action can't be undone.
Warning
This action cannot be undone and will invalidate all issued verifiable credentials and created contracts.
HTTP Request
POST /v1.0/verifiableCredentials/optout
Request headers
| Header | Value |
|---|---|
| Authorization | Bearer (token). Required |
| Content-Type | application/json |
Request body
Don't supply a request body for this method
Response message
Example response message
HTTP/1.1 200 OK
Content-type: application/json
OK
Remark
Note
If you don't have delete permissions on Key Vault we will return an error message and still opt-out
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for