@@ -69,6 +69,13 @@ token itself is never written anywhere, since that would put a bearer secret in
6969Both shapes work. A token configured as a plain list of scopes can not be given credential configurations,
7070though, so it can not be used at the credential offer and credential status endpoints (see below).
7171
72+ The name, or the fingerprint of an unnamed token, is also who owns the credential offers the token makes (see
73+ [ Credential Offer Details] ( #credential-offer-details ) ). Two tokens configured under one name are therefore one
74+ owner, by design: a token can be rotated without losing its offers, and an offering system and a support system can
75+ share their offers by sharing a name. Two integrations an operator gives the same name share them too, so give each
76+ integration a name of its own. An unnamed token owns its offers by its fingerprint, so rotating it loses them: the
77+ new token can neither list them nor change the status of what they issued (the administration screens still can).
78+
7279### Limiting a token to credential configurations
7380
7481A token's scopes say which endpoints it may call. At the credential offer and credential status endpoints, a
@@ -166,7 +173,18 @@ naming the same user each issue their own attributes.
166173
167174#### Response
168175
169- The response is a JSON object with the ` credential_offer_uri ` field containing the credential offer URI string value.
176+ The response is a JSON object with two fields:
177+
178+ * __ credential_offer_uri__ (string): the credential offer URI, which the wallet is sent to.
179+ * __ offer_id__ (string): the identifier of the offer, 64 lower-case hexadecimal characters. Keep it: it is how the
180+ caller later asks which credentials the offer produced, and changes their status (see
181+ [ Credential Offer Details] ( #credential-offer-details ) ). It is neither the pre-authorized code nor the issuer state,
182+ which redeem the offer and are for the wallet only, so it can go into the caller's own records and logs.
183+
184+ Every offer is recorded, with the principal of the token which made it as its owner (its name, or a fingerprint;
185+ see [ Naming a token] ( #naming-a-token ) ). An offer made from an administrator's session, or from the administration
186+ screens, has no owner, and no API caller can list it. The record holds no personal data: the user attributes of a
187+ pre-authorized offer stay with its code and its access token.
170188
171189An offer for the authorization code grant is redeemed once: when the wallet exchanges the code it obtained with the
172190offer for an access token. That has to happen within the issuer state lifetime (` vci_issuer_state_ttl ` ); the access
@@ -189,9 +207,9 @@ hold no email address to send the transaction code to.
189207` credential_configuration_ids ` , or the token has none (see
190208[ Limiting a token to credential configurations] ( #limiting-a-token-to-credential-configurations ) ). A configuration
191209which does not exist is answered with ` 400 ` ` invalid_request ` whatever the list says.
192- * ` 500 ` ` server_error ` : the offer could not be built, for example because the transaction code could not be mailed,
193- or a credential configuration is malformed; or the token's ` credential_configuration_ids ` are malformed. The cause
194- is in the log.
210+ * ` 500 ` ` server_error ` : the offer could not be built or recorded , for example because the transaction code could not
211+ be mailed, or a credential configuration is malformed; or the token's name or ` credential_configuration_ids ` could
212+ not be read from the configuration. The cause is in the log.
195213
196214When the wallet redeems a pre-authorized code at the token endpoint, a wrong transaction code is answered with
197215` invalid_grant ` , and one sent for an offer which has none with ` invalid_request ` , as OpenID4VCI 1.0 section 6.3 has
@@ -225,7 +243,8 @@ Response:
225243
226244``` json
227245{
228- "credential_offer_uri" : " openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fidp.mivanci.incubator.hexaa.eu%22%2C%22credential_configuration_ids%22%3A%5B%22ResearchAndScholarshipCredentialDcSdJwt%22%5D%2C%22grants%22%3A%7B%22authorization_code%22%3A%7B%22issuer_state%22%3A%2230616b68fa26b00c5a6391faffc02e4e4fd9b0023fd6a3aa29ec754e2f5e2871%22%7D%7D%7D"
246+ "credential_offer_uri" : " openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fidp.mivanci.incubator.hexaa.eu%22%2C%22credential_configuration_ids%22%3A%5B%22ResearchAndScholarshipCredentialDcSdJwt%22%5D%2C%22grants%22%3A%7B%22authorization_code%22%3A%7B%22issuer_state%22%3A%2230616b68fa26b00c5a6391faffc02e4e4fd9b0023fd6a3aa29ec754e2f5e2871%22%7D%7D%7D" ,
247+ "offer_id" : " 8f4c2a1e9d7b6053c4e1f2a8b9d0c7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0"
229248}
230249
231250```
@@ -259,7 +278,115 @@ Response:
259278
260279``` json
261280{
262- "credential_offer_uri" : " openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fidp.mivanci.incubator.hexaa.eu%22%2C%22credential_configuration_ids%22%3A%5B%22ResearchAndScholarshipCredentialDcSdJwt%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%22_ffcdf6d86cd564c300346351dce0b4ccb2fde304e2%22%2C%22tx_code%22%3A%7B%22input_mode%22%3A%22numeric%22%2C%22length%22%3A4%2C%22description%22%3A%22Please%20provide%20the%20one-time%20code%20that%20was%20sent%20to%20your%20e-mail%20address.%22%7D%7D%7D%7D"
281+ "credential_offer_uri" : " openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fidp.mivanci.incubator.hexaa.eu%22%2C%22credential_configuration_ids%22%3A%5B%22ResearchAndScholarshipCredentialDcSdJwt%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%22_ffcdf6d86cd564c300346351dce0b4ccb2fde304e2%22%2C%22tx_code%22%3A%7B%22input_mode%22%3A%22numeric%22%2C%22length%22%3A4%2C%22description%22%3A%22Please%20provide%20the%20one-time%20code%20that%20was%20sent%20to%20your%20e-mail%20address.%22%7D%7D%7D%7D" ,
282+ "offer_id" : " 3b9e7d1c5a2f4086e9c3b7a1d5f2e8c4b6a0d9e3f7c1b5a8e2d6f0c4b9a7e3d1"
283+ }
284+ ```
285+
286+ ### Credential Offer Details
287+
288+ Tells the caller which made a credential offer what the offer produced: the offer as it is recorded, and the
289+ credentials issued from it, each with the identifier the [ Credential Status] ( #credential-status ) endpoint takes.
290+ Withdrawing a credential issued from an offer is then: list the offer's credentials, and change the status of each.
291+
292+ It is served under the same settings as the [ Credential Offer] ( #credential-offer ) endpoint: the API, the VCI
293+ feature and ` ModuleConfig::OPTION_API_VCI_CREDENTIAL_OFFER_ENDPOINT_ENABLED ` . With the VCI feature switched off
294+ it is not served, unlike the credential status endpoint; the administration screens still reach the credentials.
295+
296+ #### Path
297+
298+ ` /api/vci/credential-offer/{offer_id} ` , with the ` offer_id ` the credential offer endpoint answered.
299+
300+ #### Method
301+
302+ ` GET `
303+
304+ #### Authorization
305+
306+ ` Bearer Token ` , and only from the ` Authorization ` header, for the reasons given at the
307+ [ Credential Status] ( #credential-status ) endpoint. The token needs one of the scopes of the credential offer
308+ endpoint (` VciCredentialOffer ` , ` VciAll ` , ` All ` ), has to stand for the principal which made the offer (see
309+ [ Naming a token] ( #naming-a-token ) ), and every credential configuration the offer offered has to be in its
310+ ` credential_configuration_ids ` still: an offer whose configuration has since been taken off the token's list is no
311+ longer the token's to see.
312+
313+ #### Request
314+
315+ * __ cursor__ (query parameter, optional): the ` next_cursor ` of the previous page, to ask for the page after it.
316+
317+ #### Response
318+
319+ A JSON object with the following fields. Moments are numbers of seconds since the epoch (UTC), as in a JWT.
320+
321+ * __ offer_id__ (string): the offer's identifier.
322+ * __ credential_configuration_ids__ (array of strings): the credential configurations offered.
323+ * __ grant_type__ (string): the grant the offer is redeemed with.
324+ * __ created_at__ (number): when the offer was made.
325+ * __ redeemable_until__ (number): when its pre-authorized code or issuer state expires.
326+ * __ redeemed_at__ (number or ` null ` ): when an access token was first issued for the offer, ` null ` until then. It says
327+ that a token was issued, not that a credential reached a wallet.
328+ * __ withdrawn_at__ (number or ` null ` ): reserved for withdrawing an offer; always ` null ` for now.
329+ * __ credentials__ (array): the credentials issued from the offer, in the order they were issued, at most 500 per
330+ page. Each is an object with:
331+ * __ credential_id__ (string): the credential's ` jti ` , which the credential status endpoint takes.
332+ * __ credential_configuration_id__ (string): the credential configuration it was issued from.
333+ * __ status__ (string): ` valid ` , ` invalid ` or ` suspended ` , as the credential status endpoint names them.
334+ * __ issued_at__ (number): when it was issued, to the second. The times the credential itself states are rounded
335+ (` vci_time_claim_granularity ` ), so its ` iat ` may be earlier and its ` exp ` later.
336+ * __ expires_at__ (number or ` null ` ): when it expires; ` null ` for a credential which never does.
337+ * __ next_cursor__ (string, only when there are more): pass it as ` cursor ` to get the next page. A cursor names the
338+ last credential of a page rather than a position, so credentials which expire while the caller pages do not shift
339+ the pages.
340+
341+ An access token issued for an offer buys credentials as often as its lifetime allows, so the list can grow until
342+ the token expires. A credential appears once it has been signed and before it is handed to the wallet, so a list
343+ taken after the wallet received a credential holds it. A credential issued with no Token Status List entry (its
344+ configuration is in no Status List pool) is not listed, since the entry is where the link to the offer is kept; nor
345+ is a credential once it has expired and the cron has removed what linked it to its offer. An offer is kept as long as
346+ it can still be redeemed, as long as an access token issued for it lives, and as long as a credential issued from
347+ it has not expired; then the cron removes it.
348+
349+ Errors:
350+
351+ * ` 400 invalid_request ` : the cursor is malformed.
352+ * ` 401 unauthorized ` : no bearer token, or one which is not configured.
353+ * ` 403 insufficient_scope ` : the token is configured but has none of the scopes this endpoint accepts.
354+ * ` 404 not_found ` : no offer with that identifier can be shown. An identifier which is malformed, one which is
355+ unknown or whose offer has been removed, an offer made from an administrator's session, an offer made by another
356+ principal, and an offer whose credential configuration is no longer in the token's list are all answered the same
357+ way, so that the endpoint can not be used to find out which offers exist. The log says which it was.
358+ * ` 500 server_error ` : the offer or its credentials could not be read, or the token's name or
359+ ` credential_configuration_ids ` could not be read from the configuration. The cause is in the log.
360+
361+ #### Sample
362+
363+ Request:
364+
365+ ``` shell
366+ curl --location ' https://idp.example.org/ssp/module.php/oidc/api/vci/credential-offer/8f4c2a1e9d7b6053c4e1f2a8b9d0c7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0' \
367+ --header ' Authorization: Bearer ***'
368+ ```
369+
370+ Response:
371+
372+ ``` json
373+ {
374+ "offer_id" : " 8f4c2a1e9d7b6053c4e1f2a8b9d0c7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0" ,
375+ "credential_configuration_ids" : [" ResearchAndScholarshipCredentialDcSdJwt" ],
376+ "grant_type" : " authorization_code" ,
377+ "created_at" : 1794391200 ,
378+ "redeemable_until" : 1794391800 ,
379+ "redeemed_at" : 1794391320 ,
380+ "withdrawn_at" : null ,
381+ "credentials" : [
382+ {
383+ "credential_id" : " https://idp.example.org/vc/mBS4Zt9wDRe-8sYcJUEBiZ4bGDsYY3rMHOB2Xdw4t1c" ,
384+ "credential_configuration_id" : " ResearchAndScholarshipCredentialDcSdJwt" ,
385+ "status" : " valid" ,
386+ "issued_at" : 1794391320 ,
387+ "expires_at" : 1825927320
388+ }
389+ ]
263390}
264391```
265392
@@ -324,12 +451,19 @@ status was not one of the three.
324451* ` 401 unauthorized ` : no bearer token, or one which is not configured.
325452* ` 403 insufficient_scope ` : the token is configured but has none of the scopes this endpoint accepts.
326453* ` 404 not_found ` : no credential with that identifier can have its status changed. A credential which
327- was never issued here, one issued without a ` status ` claim, one which has expired, and one issued from a
454+ was never issued here, one issued without a ` status ` claim, one which has expired, one issued from a
328455credential configuration which is not in the token's ` credential_configuration_ids ` (see
329456[ Limiting a token to credential configurations] ( #limiting-a-token-to-credential-configurations ) ), or whose
330- configuration is not recorded, are all answered the same way, so that the endpoint can not be used to find out
331- which identifiers exist. A token with ` ['*'] ` included: only the administration screens can change a credential
332- whose configuration is not recorded.
457+ configuration is not recorded, and one issued from a credential offer another principal made, are all answered
458+ the same way, so that the endpoint can not be used to find out which identifiers exist. A token with ` ['*'] `
459+ included: only the administration screens can change a credential whose configuration is not recorded.
460+
461+ A credential issued from an offer an API token made can have its status changed by that token's principal only
462+ (see [ Naming a token] ( #naming-a-token ) ), whatever the other tokens' configurations: otherwise an integration sharing
463+ a credential configuration with another could revoke, suspend or reinstate the other's credentials, whose
464+ identifiers travel inside them to every verifier they are shown to. Any other credential, one a wallet obtained
465+ without an offer or from an offer made from the administration screens, is changed under the token's credential
466+ configurations alone.
333467* ` 409 conflict ` : another change landed at the same moment and the credential ended up holding
334468something other than what was asked for. Read the current status and decide again.
335469* ` 422 unsupported_status ` : the Status List this credential belongs to was created without room for
0 commit comments