Building with Passport
Passport API v2
Data dictionary

Data dictionary (v2)

On this page you will find definitions and explanations for the data types used in the Passport XYZ stack. The Scorer, Stamp , Credential and Stamp-metadata objects require the most explanation so they are handled separately here.

The Scorer object

ValueTypeDescriptionHow to use
addressstringThe string of 20 bytes that uniquely identify an Ethereum accountIdentifies a specific account to which the payload's data relates.
scorestringThe registry/score endpoint returns a string that should be parsed as a float. It represents the result of adding the weights of all a user's Stamps.If you'd like to use your own score threshold, you can compare this score against that threshold to identify which users should be provided access.
passing_scorestringPassing score will return either true or false as its value, depending on whether the user's score exceeded the threshold score of 20, as recommended by the Passport team. You can also choose your own score threshold and use the score value if you'd prefer.If you'd like to use the Passport recommended score threshold, you can use this value to identify which users should be provided access.
last_score_timestampdatetime stringThe date and time of the request.
ISO 8601, "2023-04-28T09:35:49.159Z"
Can be used to identify when the snapshot of this data occured.
expiration_timestampdatetime stringThe date and time that the next Stamp will expire, which will subsequently reduce the score. To see when each specific Stamp expires, please use the GET /v2/stamps{address} endpoint.
ISO 8601, "2023-04-28T09:35:49.159Z"
You might want to display this score expiration to the user to remind them to return to the Passport app to refresh their score before it expires
thresholdstringThe Passport recommended score threshold that the user's score must exceed to be considered passing. The current recommended threshold is 20. You can also choose your own score threshold and use the score value if you'd prefer.If you'd like to use the Passport recommended score threshold, you can use this value to identify which users should be provided access.
errorstringDescribes any error returned by the server. Refer to the API status and error codes page for more information.Can be used to understand why a request failed.
stamp_scoresstructContains key:value pairs with Stamp names as keys and their weights for the scoring algoithm as values. This struct was introduced on December 29th, 2023, and is not available via the historical score endpoint before this point.Can be used to understand how the score was calculated.

The Stamp object

ValueTypeDescriptionHow to use
credentialstructMessage displayed in the Passport Scorer app alongside a button to trigger verification of a specific Stamp See Credentials table below for more details.This is what a Stamp actually comprises. It is associated with an Ethereum address.
itemsarray<stamp>An array containing data for each individual Stamp.Each object in this array represents a specific Stamp.
metadatastructMetadata is a struct containing id, icon, name, description, and connectMessage fields for each provider and then more granular data for each of the provider's StampsReturned from the GET /v2/stamps/{address} endpoint if the parameter include-metadata=true is also passed. Returned from GET v2/stamps/metadata endpoint for all Stamps
nextstringA pointer to the next page of returned data, if the returned data has been paginated.You can use this is a request to access a page and the subsequent page of results for a paginated response. If the value is null you are already seeing all the available information.
prevstringA pointer to the preceding page of returned data, if the returned data has been paginated.You can use this is a request to access a page and the previous page of results for a paginated response. If the value is null you are already seeing all the available information.
versionstringA version identifier for a StampReturned for each Stamp from GET /v2/stamps{address}

Credentials

A credential is a struct returned in the Stamp object. Learn more about Verifiable Credentials via their w3 specification (opens in a new tab).

This object has its own sub-fields as follows:

ValueTypeDescriptionHow to use
typestringA descriptor that shows what type of credential is presentCan be used to check that the returned data is of the expected structure for a given credential type. This is usually going to have the value VerifiableCredential.
proofstructA struct containing several fields comprising the proof that a certain action was taken, for example a signed auth token proving that an account was unlocked.Used to verify ownership of a specific Stamp
issuerhashEach Stamp issuer has a specific identifying hash provided in this field.Used to identify a Stamp issuer
@contexturlLink to the credential definition documentation.Can be used to access reference documentation for the credential type
issuanceDatedatetime stringThe date and time that the Stamp was minted.
ISO 8601, "2023-04-28T09:35:49.159Z"
Can be used to check the age of a Stamp
expirationDatedatetime stringThe date and time the Stamp should expire.
ISO 8601, "2023-04-28T09:35:49.159Z"
Can be used to automatically expire a Stamp
credentialSubjectstructContains anonymized information about the user that the Stamp is issued to. This includes a unique ID, a hash, link to the data schema and the Stamp provider name in plaintext.Can be used to connect Stamps to a user in a privacy preserving way

Stamp metadata

ValueTypeDescriptionHow to use
connectMessagestringMessage displayed in the Passport scorer app alongside a button to trigger verification of a specific StampMainly used in the Passport app, but could be used to provide appropriate message for verification in other contexts
descriptionstringShort description of what a specific Stamp demonstrates. For example, ownership of >0.5 ETHReturned in Stamp metadata, can be used to understand a specific Stamp
groupsstringIdentifier for top-level groupings of Stamps for a given providerEach provider may issue many Stamps which can be grouped together by theme, for example the Passport Provider groups Stamps by Self GTC-staking and Community GTC-staking
hashstringA unique hash representing a specific instance of a credentialUsed to prevent the same Stamp being used multiple times in a specific Scorer instance
iconstringA URL for an image to represent each Stamp providerReturned in Stamp metadata, can be used to load an icon for a Stamp provider
idstringAn identifier for a StampReturned in Stamp metadata, can be used to scrape data for a specific Stamp
namestringName of the provider issuing a given StampReturned as part of the Stamp metadata, can be used to scrape information for specific providers
stampsarrayArray containing Stamp structs for each individual Stamp. Each Stamp has name, description and hash fieldsIncluded in Stamp metadata. Used to identify specific instances of individual Stamps