Especificação de emissão da API REST de Serviço de Solicitação

A ID Verificada do Microsoft Entra inclui a API REST do Serviço de Solicitação. Essa API permite emitir e verificar uma credencial. Este artigo especifica a API REST de Serviço de Solicitação para uma solicitação de emissão. Outro artigo descreve como chamar a API REST do Serviço de Solicitação.

Solicitação HTTP

A solicitação de emissão da API REST de Serviço de Solicitação dá suporte ao seguinte método HTTP:

A solicitação de emissão da API REST de Serviço de Solicitação exige os seguintes cabeçalhos HTTP:

Construa uma solicitação HTTP POST para a API REST de Serviço de Solicitação.

https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest

A solicitação HTTP a seguir demonstra uma solicitação para a API REST de Serviço de Solicitação:

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Content-Type: application/json
Authorization: Bearer <token>

{
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "headers": {
            "api-key": "an-api-key-can-go-here"
        }
    },
    ...
}

A permissão a seguir é necessária para chamar a API REST de Serviço de Solicitação. Para obter mais informações, consulte Conceder permissões para obter tokens de acesso.

Carga de solicitação de emissão

O conteúdo da solicitação de emissão contém informações sobre sua solicitação de emissão de credenciais verificáveis. O exemplo a seguir demonstra uma solicitação de emissão usando um fluxo de código PIN com declarações do usuário, como nome e sobrenome. O resultado dessa solicitação retorna um código QR com um link para iniciar o processo de emissão.

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

O conteúdo tem as propriedades a seguir:

Atualmente, há quatro tipos de atestado de declarações que você pode enviar na payload. A ID Verificada do Microsoft Entra usa quatro maneiras de inserir declarações em uma credencial verificável e atestar essas informações com o DID do emissor. A seguir, estão os quatro tipos:

• token de ID
• Dica de token de ID
• Credenciais verificáveis por meio de uma apresentação verificável
• Declarações autoatestadas

Você pode encontrar informações detalhadas sobre os tipos de entrada em Personalizando suas credenciais verificáveis.

Tipo RequestRegistration

O tipo RequestRegistration fornece o registro de informações para o emissor. O tipo RequestRegistration contém as propriedades a seguir:

Tipo de retorno de chamada

A API REST de Serviço de Solicitação gera vários eventos para o ponto de extremidade do retorno de chamada. Esses eventos permitem atualizar a interface do usuário e continuam o processo depois que os resultados são retornados para o aplicativo. O tipo Callback contém as propriedades a seguir:

Tipo de pin

O tipo pin define um código PIN que pode ser exibido como parte da emissão. O pin é opcional e, se usado, deve sempre ser enviado fora de banda. Quando você estiver usando um PIN de código HASH, deverá definir as propriedades salt, alg e iterations. O pin contém as propriedades a seguir:

Resposta bem-sucedida

Se for bem-sucedido, esse método retornará um código de resposta (HTTP 201 Criado) e uma coleção de objetos de evento no corpo da resposta. O JSON a seguir demonstra uma resposta bem-sucedida:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "qrCode": "data:image/png;base64,iVBORw0KggoA<SNIP>"  
} 

A resposta contém as seguintes propriedades:

Quando seu aplicativo recebe a resposta, ele precisa apresentar o código QR ao usuário. O usuário escaneia o código QR, que abre o aplicativo autenticador e inicia o processo de emissão.

Resposta de erro

Se houver um erro com a solicitação, uma resposta de erro será retornada e deverá ser tratada adequadamente pelo aplicativo.

Eventos de retorno de chamada

O ponto de extremidade do retorno de chamada é chamado quando um usuário escaneia o código QR, usa o link profundo do aplicativo autenticador ou termina o processo de emissão.

O exemplo a seguir demonstra o conteúdo do retorno de chamada quando o aplicativo autenticador inicia a solicitação de emissão:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

O exemplo a seguir demonstra uma carga de retorno de chamada após o usuário concluir com êxito o processo de emissão:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

Erros de retorno de chamada

O ponto de extremidade do retorno de chamada pode ser chamado com uma mensagem de erro. A tabela a seguir lista os códigos de erro:

O exemplo a seguir demonstra o conteúdo de um retorno de chamada quando ocorreu um erro:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
} 

Próximas etapas

Saiba como chamar a API REST de Serviço de Solicitação.