Create a PDF template

This guide will show you how to create a PDF template, which is required to format a Compact or Semantic Compact Credential as a PDF document.

Prerequisites

You need the following in order to proceed with this tutorial:

• Access to Sovrin APIs. If you’re experiencing any difficulties, contact us.

• Design a PDF template and save it as a template.zip bundle file:

  • Download a Compact Credential sample PDF template.

  • Download a Semantic Compact Credential sample PDF template.

Request

Make the following request to create a Compact Credential PDF template:

POST https://api.sovrin.one/core/v2/credentials/compact/digitalpass/apple/templates

{
    "template": {
        "value": fs.createReadStream("pass.zip"),
        "options": {
            "filename": "WorkingStoreCard.pass.zip",
            "contentType": null
        }
    },
    "name": "example",
    "fileName": "example.pkpass",
    "teamIdentifier": "xxx",
    "passTypeIdentifier": "xxx",
    "wwdr": "xxx",
    "signerCert": "xxx",
    "signerKey": "xxx",
    "signerKeyPassphrase": "xxx",
}

• template: Include your template files.

• name: Insert a name to identify this Apple digital pass template.

• fileName: Insert the file name that will be assigned to Apple digital passes created from this template.

• teamIdentifier: The Team ID for the Apple Developer Program account that registered the pass type identifier.

tip

To find your Team ID, do the following:

1. Open Keychain Access, and select your certificate.
2. Select File > Get Info, and find the Organizational Unit section under Details. This is your Team ID.

You can also find your Team ID by looking at your organization profile in Member Center.

• passTypeIdentifier: The pass type identifier that’s registered with Apple. The value must be the same as the distribution certificate used to sign the pass.

tip

Every pass has a pass type identifier associated with a developer account. Pass type identifiers are managed in the Member Center by a team admin. To build this pass, request and configure a pass type identifier. (You can’t use the pass type identifier that is already in the pass because it isn’t associated with your developer account)

To register a pass type identifier:

1. In Certificates, Identifiers & Profiles select Identifiers.
2. Under Identifiers, select Pass Type IDs.
3. Click the plus (+) button.
4. Enter the description and pass type identifier, and click Submit.

• wwdr: Apple G1 or G4 worldwide developer relations intermediate certificate.

• signerCert: Apple pass signer certificate.

• signerKey: The encrypted key of the Apple pass signer certificate

• signerPassphrase: Passphrase for the encrypted key

You can make a similar request to a different endpoint to create a Semantic Compact Credential Apple pass template:

POST https://api.sovrin.one/core/v2/credentials/compact-semantic/digitalpass/apple/templates

Response

{
    "id": "1b04f0ee-8e3e-4153-a0e0-8603a10e7f0a",
    "name": "example",
    "passType": "apple",
    "metadata": {
        "fileName": "example.pkpass",
        "teamIdentifier": "xxxxx",
        "passTypeIdentifier": "xxxxx"
    }
}

• id: This is a unique identifier for this Apple digital pass template. You will use it as the templateId when formatting a Compact Credential as an Apple digital pass.

• All other fields in the response include information retrieved from your Apple digital pass template.

Errors may occur in the following scenarios:

• Unable to decompress the bundle.

• pass.json is missing from the bundle is malformed.

• Required fields in pass.json are not available.

• The file name contains a special character that is not supported by the Apple pass template endpoint.

• The bundle file exceeds the maximum size allowed.

tip

If you ever need to update any issuer information such as teamIdentifier, passTypeIdentifier, wwdr, signerCert, signerKey or signerKeyPassphrase, it is highly recommended to create a new template. However, you can also update an existing template.