Spesifikasi penerbitan REST API Layanan Permintaan

ID Terverifikasi Microsoft Entra menyertakan REST API Layanan Permintaan. API ini memungkinkan Anda untuk menerbitkan dan memverifikasi kredensial. Artikel ini menentukan REST API Layanan Permintaan untuk permintaan penerbitan. Artikel lain menjelaskan cara memanggil Request Service REST API.

Permintaan HTTP

Permintaan penerbitan Request Service REST API mendukung metode HTTP berikut:

Permintaan penerbitan Request Service REST API memerlukan header HTTP berikut:

Buat permintaan HTTP POST ke Permintaan Layanan REST API.

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

Permintaan HTTP berikut menunjukkan permintaan ke REST API Layanan Permintaan:

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"
        }
    },
    ...
}

Izin berikut diperlukan untuk menghubungi Request Service REST API. Untuk informasi selengkapnya, lihat Memberikan izin untuk mendapatkan token akses.

Payload permintaan penerbitan

Payload permintaan penerbitan berisi informasi tentang permintaan penerbitan kredensial yang dapat diverifikasi. Contoh berikut menunjukkan permintaan penerbitan dengan menggunakan alur kode PIN dengan klaim pengguna, seperti nama depan dan nama belakang. Hasil dari permintaan ini menampilkan kode QR dengan tautan untuk memulai proses penerbitan.

{
  "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"
}

Payload berisi properti berikut:

Saat ini ada empat jenis pengesahan klaim yang dapat Anda kirim di payload. Microsoft Entra Verified ID menggunakan empat cara untuk memasukkan klaim ke dalam kredensial yang dapat diverifikasi dan membuktikan informasi tersebut dengan DID pengeluar sertifikat. Berikut keempat jenisnya:

• Token ID
• Petunjuk token ID
• Kredensial yang dapat diverifikasi melalui presentasi yang dapat diverifikasi
• Klaim yang dibuktikan sendiri

Anda dapat menemukan informasi mendetail tentang jenis input di Menyesuaikan kredensial Anda yang dapat diverifikasi.

Jenis RequestRegistration

Jenis RequestRegistration menyediakan pendaftaran informasi untuk penerbit. Jenis RequestRegistration berisi properti berikut:

Jenis panggilan balik

Request Service REST API membuat beberapa peristiwa ke titik akhir panggilan balik. Peristiwa ini memungkinkan Anda untuk memperbarui antarmuka pengguna dan melanjutkan proses setelah hasilnya ditampilkan ke aplikasi. Jenis Callback berisi properti berikut:

Jenis Sematkan

Jenis pin menentukan kode PIN yang dapat ditampilkan sebagai bagian dari penerbitan. pin adalah opsional, dan, jika digunakan, harus selalu dikirim secara out-of-band. Saat menggunakan kode PIN HASH, Anda harus menentukan properti salt, alg, dan iterations. pin berisi properti berikut:

Respons berhasil

Jika berhasil, metode ini menampilkan kode respons (HTTP 201 Dibuat), dan koleksi objek peristiwa di isi respons. JSON berikut menunjukkan respons yang berhasil:

{  
    "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>"  
} 

Respons berisi properti berikut:

Saat aplikasi Anda menerima respons, aplikasi perlu memberikan kode QR kepada pengguna. Pengguna memindai kode QR, yang membuka aplikasi pengautentikasi dan memulai proses penerbitan.

Respons kesalahan

Jika ada kesalahan dengan permintaan, respons kesalahan dikembalikan. Aplikasi harus menangani respons dengan tepat.

Peristiwa panggilan balik

Titik akhir panggilan balik dipanggil saat pengguna memindai kode QR, menggunakan tautan langsung aplikasi pengautentikasi, atau menyelesaikan proses penerbitan.

Contoh berikut menunjukkan payload panggilan balik saat aplikasi pengautentikasi memulai permintaan penerbitan:

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

Contoh berikut menunjukkan payload panggilan balik setelah pengguna berhasil menyelesaikan proses penerbitan:

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

Kesalahan panggilan balik

Titik akhir panggilan balik mungkin dipanggil dengan pesan kesalahan. Tabel berikut mencantumkan kode galat:

Contoh berikut menunjukkan payload panggilan balik saat terjadi kesalahan:

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

Langkah berikutnya

Pelajari cara memanggil REST API Layanan Permintaan.