How does a client keep track of which cards it created to prevent incorrectly handling objects created by other systems

[devraj]

One of the most common use cases for our API is to automate provisioning of mobile passes, portion of this use case also entails reissuing passes where ideally we take away the pass that was issued previously. Common scenarios for these are:

• The use has a new mobile device and would like to reenrol for a corporate pass
• Invitation for a pass has expired and the user wants to try again
• General debugging exercise to see if the cypher is faulty

In all these instances it would be nice to be able to clean up the previously issued pass by our middleware. The challenge seem to be as follows:

• When creating a mobile credential through the API it doesn't return a response body to indicate the newly created object
• While we would have the href for a card_type it is in theory possible for another system (at a minimum the command centre) to create a pass of the same type
• From what I can see the cards payload does not have a created or updated date and you can't GET the card object on it's own

"cards": [
    {
        "bleFacilityId": 884878,
        "credentialClass": "mobile",
        "credentialId": "83010eda-d7ba-4f20-8e9a-3d50ce301425",
        "href": "https://commandcentre-api-au.security.gallagher.cloud/api/cardholders/4665/cards/d725c6....",
        "invitation": {
            "email": "kritis@...au",
            "href": "https://commandcentre-ap-southeast-2.security.gallagher.cloud/api/invitations/KQAY-....",
            "mobile": "0411....",
            "singleFactorOnly": true,
            "status": "expired"
        },
        "number": "0411....",
        "status": {
            "type": "active",
            "value": "Active"
        },
        "type": {
            "href": "https://commandcentre-api-au.security.gallagher.cloud/api/card_types/2550",
            "name": "Mobile Credential"
        }
    }
],

I think we should outline some strategies in the documentation as to how we can keep a track of the objects we are creating, also possible to address this in #9

[devraj]

Here's a rudimentary examples in Python using the library.

We fetch the initial state of the cardholder so we can cache the cards they have:

cardholder = await Cardholder.retrieve(cardholder_summary.id)
original_cards = cardholder.cards

Now perform the routine to create the card you are after. You would then fetch the cards again and and the filter to see the new card item

    # Build a set of original card hrefs for O(1) lookups
    original_hrefs = {str(c.href) for c in original_cards}

    # Find the first card in updated_cardholder that wasn't in the original set
    new_card = next(
        (card for card in updated_cardholder.cards if str(card.href) not in original_hrefs),
        None
    )

Note

You have to wait about 5s between creating the card and fetching the cardholder details again to ensure that the command centre has provisioned the pass

You should additionally check for the card type href to make sure you are filtering down the right card type and the invitation status.

This still does not help with the race condition if another source created a card between you provisioning a card and fetching it again, especially if the other card is of the same type and the invitation remains unaccepted.

What would help (not sure if this possible because the card object doesn't exists) is if the PATCH endpoint for the cardholder (which we use to provision the card) returned a response with the href of the card being provisioned as a result of our request.