Passport API v2 migration guide

Migrating to Passport API V2 is designed to be straightforward. This guide outlines the key changes and provides step-by-step instructions to help you update your integration smoothly.

But first, why should you migrate?

• Retrieve user scores with a single, intuitive GET request.
• Utilize new endpoints to access historical scores and Stamp data.
• Gain access to more data to proactively prevent and resolve misunderstandings.
• Retrieve both binary and numeric scores within the same payload
• Benefit from a more unified API endpoint URI structure.

If you'd prefer to learn by doing, please visit our API playground (opens in a new tab) to see the changes in action. If you'd prefer to learn via our reference docs, please visit our API reference.

Key changes to address

1. The base URL
2. Simplified score retrieval
3. Updated endpoint URIs
4. Accessing historical data
5. Unified Scorer types
6. Additional Stamp data in score payload

The base URL

In August 2024, the Passport workstream spun out of Gitcoin, creating Passport XYZ.

We have been working on separating our infrastructure from Gitcoin, and the API base URL is finally getting its update.

• Previous Base URL: https://api.passport.gitcoin.co (opens in a new tab)
• New Base URL: https://api.passport.xyz (opens in a new tab)

Action Required: Update all instances of the base URL in your application to the new URL.

Simplified score retrieval

Background

In V1, retrieving a user's score involved:

• Submitting the Passport for scoring using a POST request.
• Retrieving the score using a GET request.

This process was counterintuitive and could lead to confusion and stale scores if only the GET endpoint was used.

What's new in v2

• Single GET Request: Retrieve the latest score and Stamp data with one GET request.
• No POST Required: Eliminates the need to submit the Passport for scoring.

Endpoint changes

• From V1: POST /registry/submit-passport
• To V2: GET /v2/stamps/{scorer_id}/score/{address}

Action Required: Replace any POST /registry/submit-passport requests with GET requests to the new endpoint.

Updated endpoint URIs

We've adopted a more consistent, object-oriented design for our API endpoints.

Endpoint mapping

Accessing historical data

New Feature in V2

• Endpoint: GET /v2/stamps/{scorer_id}/score/{address}/history
• Functionality: Retrieve a user's score and Stamp data from a specific date and time.

Note: Access to this endpoint requires your API key to be allowlisted.

Action Required for use:

• Request Access: Fill out the access request form (opens in a new tab) to have your API key allowlisted.
• Update Implementation: Incorporate the new endpoint into your application if you need historical data.

Unified Scorer types

Background

In V1, you had to choose between two Scorer types:

• Unique Humanity
• Unique Humanity: Binary

This differentiation added complexity and could lead to confusion.

What's New in V2

• Unified Scoring: Both numeric and binary scores are included in all payloads.
• Simplified Choices: No need to choose a Scorer type; you can use the score that best fits your application.

Example v2 Payload

{
  "address": "0x9c4de275772297e8fd4c458e6844f4e92ac82b74",
  "score": "31.885",
  "passing_score": true,
  "threshold": "20",
  "last_score_timestamp": "2024-12-02T22:21:25.723470+00:00",
  "expiration_timestamp": "2025-01-05T20:29:44.441000+00:00",
  "error": null,
  "stamps": {
    "Discord": {
      "score": "0",
      "dedup": true,
      "expiration_date": "2025-2-05T03:25:24.321000+00:00"
    },
    "Ens": {
      "score": "0.408",
      "dedup": false,
      "expiration_date": "2025-01-05T20:29:44.441000+00:00"
    }
  }
}

Action Required: Adjust your application's logic to handle the new payload structure and use the appropriate score type.

Additional Stamp data in score payload

Deduplication field

To prevent multiple Passports from verifying the same credential (enhancing security against Sybil attacks), Stamps are deduplicated across addresses.

• New Field: dedup
• Purpose: Indicates whether a Stamp has been deduplicated and thus does not contribute to the score.

Example

"stamps": {
  "Discord": {
    "score": "0",
    "dedup": true,
    "expiration_date": "<alt_date>"
  },
  "Ens": {
    "score": "0.408",
    "dedup": false,
    "expiration_date": "<date>"
  }
}

In the above example, you'll notice that the Discord Stamp is deduplicated, meaning another address has also verified this same credential. As a result, the user received a 0 score for that Stamp. You will also note that a different expiration date returns when dedup=true. This date represents when the credential verified by the other address will expire, rather than when this credential will expire.

You will also see that the ENS Stamp was not deduplicated, meaning the 0.408 score was included in the user's overall unique humanity score.

Action Required:

• Handle Deduplication: Update your application to interpret the dedup field and inform users if their Stamps are affected.
• User Communication: Consider displaying warnings to users about deduplicated Stamps.

Stamp expiration date

• New Field: expiration_date for each credential.
• Purpose: Indicates when each specific Stamp will expire.

Action required:

• Monitor Expirations: Use the expiration_date to notify users about upcoming Stamp expirations.
• Update Logic: Ensure your application considers Stamp expiration dates in its functionality.

Next Steps Checklist

1. Update Base URL to https://api.passport.xyz (opens in a new tab).
2. Modify all API endpoint URIs to the new V2 structure.
3. Replace POST requests with GET requests for score retrieval.
4. Update your data models and logic to accommodate new fields (passing_score, dedup, expiration_date).
5. If needed, submit the access request form for the historical endpoint and build it into your integration.
6. Thoroughly test your application to ensure all changes work as expected.

If you have questions or need support, you can chat with us on our developer support channel on Telegram (opens in a new tab).