Reseller-style partners can link their users to authorised Sendle tracking pages. These special, authorised pages let your users access tools for managing orders, and also see extended order information.

With these links users can self-serve common support tasks, depending on their role in the transaction. This provides users a similar support experience to the one they'd receive if they booked a parcel via the Sendle Dashboard. These support tools are important as they:

• Provide users with common tools at their fingertips, improving their experience.
• Collect required information before a support ticket is opened, speeding up resolution.
• Funnel support requests about the parcel to Sendle, reducing the load on your team.
• Let us update processes and launch new order tools without changes or development needed on your side.

Authorised Tracking Pages also offer more detailed information compared to the standard tracking pages. Public tracking pages don't expose sensitive details such as sender & receiver information, addresses, pickup locations, or agent addresses.

These pages are accessed via cryptographically signed links that are generated by your integration. They do require development work to implement, but end up reducing a lot of support and operational overhead.

❗️

If you choose not to integrate the Authorised Tracking Pages, users will need to sign up or claim their account on Sendle.com to be able to access the full suite of tools.

Where to add these?

We recommend linking to the authorised tracking page wherever the sender/receiver would normally see the Sendle Reference. This can be in your app, on web pages, or in emails sent to those users.

When adding these links, make sure you're sending the right token (sender vs receiver) to the right user.

Available Support Tools

Here are the tools users can access, depending on their role in the order.

Some tools are optional and can be disabled depending on how your account is configured. This is useful when an action may interfere with your internal processes or be a fraud risk. If you'd like us to disable certain tools on your authorised tracking pages, let your partnerships liaison know.

Technical Integration

Authorisation

Authorisation is handled by embedding a JSON Web Token (JWT) in a tracking page URL. These tokens are created and managed by you, and are signed using a secret encryption key you control.

A great introduction to JSON Web Tokens can be found on the JWT website. There you will also find a token debugger and library support.

We verify the token's signature and authorise access to the tracking page for the user. If we are unable to verify the token's signature then we fall back to displaying the public tracking page for the order.

A JWT-enabled tracking link must contain the ref parameter, and the JWT embedded as the URL fragment:

https://track.sendle.com/tracking?ref=<sendle reference>#<JSON web token>

For example:

https://track.sendle.com/tracking?ref=S3ND43#eyJhbGciOiJFUzI1NiIsImtpZCI6ImY1MTY2YTY3LTVkNzEtNGMzYy05MGJiLWQxMDRlZjZlYjE3OSIsImFsZyI6IkVEMjU2In0.eyJyZWYiOiJTM05ENDMiLCJyb2xlIjoic2VuZGVyIiwiaWF0IjoxNTE2MjM5MDIyLCJqdGkiOiJhZTBlMmQ4ZS0yODdlLTRlZmItODgzNi05NWI2NzEwYzhjZTIifQ.rWz6IgAm5maae-XSyyzZD9e--_HlVNDwlSZv6JZLVEvwcZlBTn6WirpccSmlgAyPrP8ZHZjqWqcmV_Ob-iorUw

The JWT contains the Sendle Reference, as well as the intended role of the user accessing the tracking page (sender or receiver).

Sandbox & Testing

It is not possible to use these keys or JWTs with our Sandbox.

For testing, we recommend creating and cancelling a drop-off test order on your production account, and then accessing that page using a production JWT. Using drop-off rather than pickup will make sure a driver isn't dispatched to collect the order.

Key Management

We use ES256 for signing token payloads. This employs the Elliptic Curve Digital Signature Algorithm (ECDSA) using the P-256 curve and the SHA-256 hash algorithm.

Generation

Before you can sign tokens, you must first generate a signing keypair. A keypair is made up of a private key and a public key.

• You use the private key to sign tokens. This key is secret and should be kept out of version control.
• The public key what we use to verify your tokens' signatures. This key is public and can be sent over email or stored in version control.

This console command will generate a private key called sendle_private.pem:

$ openssl ecparam -name prime256v1 -genkey -noout -out sendle_private.pem
$ cat sendle_private.pem 
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIFUNarBPTxGnpg81tPB/Sa5deyNlYUDn5vD3rmQr+oJUoAoGCCqGSM49
AwEHoUQDQgAE7xIQwNR6AVyh5t4mDBqTIRuTA+JSSm4+yb7YEW9SqL9NtImCkuJv
jKx7IBnFuLDKh6roKvQgcm6GZZE8xO/Msw==
-----END EC PRIVATE KEY----- 

This console command will generate a public key derived from the private key:

$ openssl ec -in sendle_private.pem -pubout -out sendle_public.pem
$ cat sendle_public.pem
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7xIQwNR6AVyh5t4mDBqTIRuTA+JS
Sm4+yb7YEW9SqL9NtImCkuJvjKx7IBnFuLDKh6roKvQgcm6GZZE8xO/Msw==
-----END PUBLIC KEY-----

Email your public key to [email protected]. Your private key must be kept secret, do not send it to us. Once we have imported the public key we will send you a corresponding key ID. This ID must be included in all JWT headers as kid.

Rotation

Periodically rotating encryption keys helps mitigate the risk of a compromised key. Multiple active keys are allowed, which means that you can migrate to a new key at your own pace.

Simply generate a new keypair and send us the public key. When you're ready to invalidate the old key, just let us know.

Invalidation

If you suspect a private key has been compromised, generate a new key pair and send us the new public key, along with the compromised kid. We will invalidate the old one as soon as possible.

Token Format

Header parameters

All header parameters are required:

• kid: the ID of your supplied public key.
• alg: the signature algorithm. Must be set to "ES256".

Example Header:

{
  "kid": "f367debf-8eed-4ed7-815c-ad96afa60ab7",
  "alg": "ES256"
}

Payload

Required Claims

• ref: the order’s Sendle Reference.
• role: the user role that should be authorised. This must be either "sender" or "receiver".
• jti: a unique value that identifies the token. Using a UUID is recommended but not required.
• iat: the token creation time. This should be represented as a Unix timestamp.

Optional Claims

• exp: the expiration time of the token. This should be represented as a Unix timestamp.

Example Payload:

{
  "ref": "SNFJJ3",
  "role": "sender",
  "iat": 1516239022,
  "exp": 1518831022,
  "jti": "ae0e2d8e-287e-4efb-8836-95b6710c8ce2"
}

Signatures

Token contents are signed cryptographically to prevent tampering. All tokens must be signed using the ES256 algorithm. Tokens signed with any other algorithm will not be valid.

URL Generation Code Samples

Security Considerations

Your private key is the only thing that's required to create valid tokens and management links for your users' orders. As such, it is vital that your private key is kept secret. If you suspect that a key has leaked, please contact us immediately.

Ensure that you are not saving JWTs to any services that track outbound clicks such as Google Analytics. If you suspect that an individual JWT has been leaked, simply regenerate it and contact us with the compromised token's ID (jti).

We recommend generating JWTs on the fly rather than persisting them to a datastore. It will be much easier to rotate or invalidate encryption keys when you don’t have to bulk-update persisted tokens.