Data dictionary
⚠️
Please note:
In November 2024, we soft-launched Passport API v2.
We have not announced any deprecation or retirement timelines for v1 yet, but do strongly recommend using v2 moving forward.
You can learn more about the differences between v1 and v2 via our migration guide.
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. Other types found across the Passport stack are defined in "Other data".
The Scorer object
| Value | Type | Description | How to use |
|---|---|---|---|
address | string | The string of 20 bytes that uniquely identify an Ethereum account | Identifies a specific account to be scored |
score | string | The 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. | Returned from registry/score. Can be used to gate access to content. |
status | string | Shows whether a server request is PROCESSING or DONE. | Included in responses from registry/score |
last_score_timestamp | datetime string | The date and time of the previous request made to the Scorer instance. For example, "2023-04-28T09:35:49.159Z" | Returned by the registry/score and registry/submit-passport endpoint |
expiration_date | datetime string | The date and time that the next upcoming Stamp will expire, which will subsequently reduce the score. To see when each specific Stamp expires, please use the GET /stamps endpoint. | 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 |
evidence | struct | When the binary Scorer is selected, this field is used to explain why the return value was 0 or 1. Specifically, the returned data shows the threshold score required to return 1, and the actual score the Passport received. The current score threshold for a passing score is 20. | You can use this to check the reasoning behind a binary Passport score, and understand why a Passport was decided to be Sybil (0) or non-Sybil (1). |
error | string | Describes any error returned by the server. Refer to the API status and error codes page for more information. | Used to understand why a request failed. |
stamp_scores | struct | Contains key:value pairs with stamp names as keys and their weights for the scoring algoithm as values. |
The Stamp object
| Value | Type | Description | How to use |
|---|---|---|---|
credential | struct | Message 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. |
items | array<stamp> | An array containing data for each individual Stamp. | Each object in this array represents a specific Stamp. |
metadata | struct | Metadata 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 Stamps | Returned from the registry/stamps endpoint if the qualifier include-metadata=true is also passed. Returned from registry/stamp-metadata for all Stamps |
next | string | A 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. |
prev | string | A 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. |
version | string | A version identifier for a Stamp | Returned for each Stamp from registry/stamps |
Credentials
A credential is a struct returned in the Stamp object. It has its own sub-fields as follows:
| Value | Type | Description | How to use |
|---|---|---|---|
type | string | A descriptor that shows what type of credential is present | Can 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. |
proof | struct | A 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 |
issuer | hash | Each Stamp issuer has a specific identifying hash provided in this field. | Used to identify a Stamp issuer |
@context | url | Link to the credential definition documentation | Can be used to access reference documentation for the credential type |
issuanceDate | datetime string | The date and time that the Stamp was minted. For example, "2023-04-28T09:35:49.159Z" | Can be used to check the age of a Stamp |
expirationDate | datetime string | The date and time the Stamp should expire. For example, "2023-04-28T09:35:49.159Z" | Can be used to automatically expire a Stamp |
credentialSubject | struct | Contains 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
| Value | Type | Description | How to use |
|---|---|---|---|
connectMessage | string | Message displayed in the Passport scorer app alongside a button to trigger verification of a specific Stamp | Mainly used in the Passport app, but could be used to provide appropriate message for verification in other contexts |
description | string | Short description of what a specific Stamp demonstrates. For example, ownership of >0.5 ETH | Returned in Stamp metadata, can be used to understand a specific Stamp |
groups | string | Identifier for top-level groupings of Stamps for a given provider | Each 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 |
hash | string | A unique hash representing a specific instance of a credential | Used to prevent the same Stamp being used multiple times in a specific Scorer instance |
icon | string | A URL for an image to represent each Stamp provider | Returned in Stamp metadata, can be used to load an icon for a Stamp provider |
id | string | An identifier for a Stamp | Returned in Stamp metadata, can be used to scrape data for a specific Stamp |
name | string | Name of the provider issuing a given Stamp | Returned as part of the Stamp metadata, can be used to scrape information for specific providers |
stamps | array | Array containing Stamp structs for each individual Stamp. Each Stamp has name, description and hash fields | Included in Stamp metadata. Used to identify specific instances of individual Stamps |
GTC staking
| Value | Type | Description |
|---|---|---|
users | array | Contains the specified address's staking data, including a stakes object that contains data on how much and when a user staked GTC on themselves, and the xstakeAggregate, which contains data on how much a user has staked on other community members and when. |
stakes | array | Contains one or multiple stake objects, which includes data on how much GTC the specified user has staked on themselves. This array will include a different object for each round the user had staked any GTC on themselves. |
stake | string | Represents the number of GTC the user has staked on themselves in a specified round. |
round | object | Contains the ID of the round in which the associated stake amount was staked. |
id | number | Represents the round in which the associated stake amount was staked. |
xstakeAggregates | array | Contains one or multiple stake objects, which includes data on how much GTC the specified user has staked on themselves. This array will include a different object for each round the user had staked any GTC on themselves. |
total | string | Represents the total number of GTC the user staked on community members in a specified round. |
Other data
| Value | Type | Description | How to use |
|---|---|---|---|
API-Key | string | An authorization token generated by the Scorer app giving you access to a Scorer instance on the Passport server. | Include this API key as part of your request headers. |
nonce | int | A transaction counter for an address that is used in signing to prevent certain types of attack | This is an optional field that can be provided to submit-passport for additional verification. Today access to Scorers is controlled using API keys only by default. |
scorer_id | string | Scorers are instantiated with unique IDs known as scorer_ids. | Create a Scorer in the Scorer app to receive a scorer_id. Then this value links your API requests to a specific Scorer instance matching your API key |
signature | string | Some workflows require a Scorer owner to demonstrate their ownership by signing a message with the Scorer owner's private key. | This is an optional field that can be provided to submit-passport for additional verification. Today access to Scorers is controlled using API keys only by default. |