GET /v0/project

This endpoint fetches details for a specific project tied to your account. The data retrieved includes the unique identifier (id) of the project, which follows the universally unique identifier (UUID) format. It also provides the name of the project, which can be used to easily identify the project across various platforms or interfaces.

In addition, the project's associated timezone is returned. This can be essential for understanding and scheduling time-sensitive operations related to the project.

Lastly, the keyCreated boolean value indicates whether a key has been created for the project. This piece of information can be vital for determining the project's readiness for certain operations and integrations that may require a project key.

GET /v0/project

This endpoint retrieves a comprehensive set of statistical data tied to a specific project. The statistics include the total number of passes and scan counts, as well as a detailed breakdown of platform-specific metrics for Apple and Google. These platform metrics include the total number, registered, and expired counts.

Furthermore, this endpoint also provides an array of recent activities, encapsulating key information such as the platform, chain, owner address, network, timestamps of creation, expiry and last scan, as well as data on scans and registrations. It also provides action details and timestamps.

POST /v0/passes

This endpoint allows you to generate an Apple or Google pass based on specific wallet signatures.

Using this feature, you can create a digital representation of ownership or affiliation, similar to a digital card or pass, which can be added to a user's Apple Wallet or Google Pay. This pass can be created to represent various forms of ownership or involvement, such as the ownership of a wallet, possession of a particular NFT, or even attachment to one or multiple existing policies.

GET /v0/passes

This endpoint fetches a list of all passes associated with your project. Each pass represents an Apple or Google pass that has been generated for a specific wallet, NFT, or policy.

To tailor the response to your specific needs, you have the flexibility to filter the passes based on multiple parameters including scanning times, creation times, expiration status, platform type (Apple or Google), chain type, network, owner`s wallet address, contract address, and token ID.

The endpoint also allows for sorting the results based on a specific field such as id, ownerAddress, createdAt, lastScannedAt, expiredAt, or platform. The order of the results can be set to ascending or descending using the asc query parameter.

You can also manage the number of results returned with the limit parameter and skip certain results using the offset parameter. By default, the response will include a maximum of 50 passes.

Each retrieved pass will contain comprehensive details including the ID, platform, blockchain network, owner address, token ID, contract address, creation time, last scanned time, and expiration status.

GET /v0/passes/{id}

This endpoint enables you to fetch the details of a specific pass by its unique identifier (ID). The pass ID could either be obtained from the creation of the pass or by querying the endpoint GET /v0/passes.

The pass details returned will encompass all pertinent data regarding the pass, including the platform it pertains to (Apple or Google), associated blockchain network, owner's wallet address, token ID, contract address, creation time, last scanned time, and expiration status.

To delve into the pass's scan history, you have the option to include parameters scanHistoryStartTime and `scanHistoryEndTime``. These parameters help filter out barcode scans in the pass's history that occurred within the specified time range. The time is provided as a Unix timestamp in seconds.

PATCH /v0/passes/{id}

This endpoint enables you to update specific fields of an existing pass for either Apple Wallet or Google Wallet. The pass ID, which is a mandatory parameter, helps identify the specific pass to be updated.

You can modify various pass details such as the encoded message in the barcode, custom images on your pass, or other aspects of the pass linked to Apple or Google platforms.

Moreover, if you want to change the barcode information, you can provide the updated details in the request body following the BarcodeInput schema.

Changes in pass details related to Apple Wallet or Google Wallet can also be made, guided by their respective schemas, i.e., PublicApplePass or PublicGooglePass.

DELETE /v0/passes/{id}

This endpoint invalidates a pass associated with the provided ID. Upon executing this operation, the pass will be removed from the user's Apple Wallet or Google Wallet, thereby preventing any further use. Please note that once a pass is invalidated, it cannot be reinstated; a new pass must be generated if required.

Note: A new API endpoint will be released soon, which will provide the functionality to reinstate an existing pass if required.

It's crucial to understand that invalidating a pass does not result in the deletion of its record from the database. Rather, it simply modifies the status of the pass to inactive, indicating that the pass is no longer in use.

GET /v0/passes/{id}/distribute

This endpoint facilitates the redistribution of a pass, meaning it allows for the retrieval of a specific Apple Wallet or Google Wallet pass URL. Users can access this URL to download their respective passes.

The mandatory parameter is the pass ID or the user-provided externalId. It uniquely identifies the specific pass you want to redistribute.

Upon success, the response will include the file URL from where the user can download their pass. For Apple passes, an additional file buffer will be returned.

Redistributing a pass is particularly useful in cases where a pass needs to be reissued, if there is an update in the pass details, or if the user misplaced the initial pass. This helps maintain access to the services associated with the pass without any disruptions.

Note: Distribution links are designed to expire automatically 48 hours after they are first accessed as a security measure. Additionally, any pre-existing distribution links will automatically expire upon the creation of a new link for the same pass.

GET /v0/scan

Verify ownership of a token by scanning the barcode on a pass. ethpass will once again read the on-chain owner of the token linked to the pass, and return a successful response if the ownership is accurate.

See our tips on scanning QR codes.

POST /v0/policies

This endpoint allows you to create a new policy within your project.

A policy includes attributes such as the policy name, the chain on which it operates, the rule evaluation method, the minimum number of rules required, and the specific array of rules applicable to that policy.

GET /v0/policies

This endpoint provides a comprehensive list of all policies that have been created in your project.

Each policy retrieved will include detailed attributes such as the policy name, the type of chain it operates on, the rule evaluation criteria, the minimum number of rules required, and an array of associated rules.

GET /v0/policies/{id}

This endpoint retrieves detailed information for a specific policy that has been created within your project.

The retrieved policy includes an array of comprehensive attributes, such as the policy name, the type of chain it operates on, the rule evaluation method, the minimum number of rules required, and an extensive list of associated rules.

PATCH /v0/policies/{id}

This endpoint allows you to update the details of an existing policy within your project.

Updating a policy entails modifying the existing attributes such as the policy name, the type of chain it operates on, the rule evaluation method, the minimum number of rules required, and the specific set of associated rules.

DELETE /v0/policies/{id}

This endpoint enables you to delete a specific policy associated with your project.

Deleting a policy involves the removal of the existing set of rules and parameters. This action is generally taken when a policy is no longer necessary or relevant to your project's current requirements or operational strategy.

This endpoint verifies provided policies against the provided wallet addresses. Each policy object includes its identifier, validation status, and an array of rules. These rules contain their respective identifier, type, satisfaction status, and associated data.

The endpoint processes each address and policy pair, checking if the conditions of each policy rule are met. If a policy is invalid (for instance, if a rule within the policy is not satisfied), it returns a detailed error message indicating the policy ID and the reason for its failure. In the case of any other error during the execution, an appropriate error message is returned.

The successful response includes the same array of wallet addresses and policies, but each policy now also includes a satisfiesAllPolicies boolean indicating if all its rules were satisfied. Additionally, each rule in a policy includes a 'valid' boolean showing if the rule was satisfied, and a 'results' object containing the outcomes of the rule validation.