Transcend

The Transcend Guide to Privacy

Welcome to the Transcend Docs. You'll find comprehensive guides and documentation to help you start working with Transcend as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides    API Reference

Authentication

All Transcend APIs require authentication:

Security Tip: HTTPS only

All requests must be made over HTTPS. Requests not made over HTTPS will be rejected.

API Keys

On your Developer Settings → tab you can issue and manage API keys. Each API key can be assigned Scopes that dictate what that API key is authorized to do.

Creating API Keys

When you want to use one of our API methods, you should issue a new API key on the Developer Settings → tab. Typically you only need one API key per server, and you can attach scopes to give that key a set of permissions. When you add a new Data Silo, you will have the option of issuing a new API key or assigning the scope for that data silo to an existing API key.

The Authorization Header

Every request must include a header: Authorization with the value of your API key.

Authorization: 
request.post('https://api.transcend.io/v0/data-subject-request', {
  headers: {
    Authorization: ''
  },
  body: {
  	...
  },
  json: true
});
req = urllib2.Request('https://api.transcend.io/v0/data-subject-request')
req.add_header('Content-Type', 'application/json')
req.add_header('Authorization', '')

Cycling API Keys

These API keys should be treated as secrets. They should never be committed to code and they should be cycled regularly. We will remind you when it is a good time to cycle your keys.

The simplest way to cycle a key is to do the following:

  1. Duplicate an existing key
  1. Swap out the new key for the old key in your next deployment
  2. Delete the old key

Security Tip: Never commit your API and cycle regularly

You should make sure you manage your API keys strictly. They should be kept in your private key store or environment variables.

Asymmetric Webhook Signing

Every time Transcend sends one of your servers a webhook notification, Transcend will sign the request with the header . This header is a JSON Web Token → that is signed by our API server's private key. We expose our public key for you to verify against at https://api.transcend.io/public-keys/transcend-webhook-signing-key.

Verify the webhook JWT

Transcend uses an Elliptic Curve Digital Signature Algorithm - Elliptic Curve Digital Signature Algorithm - (ECDSA) This is an elliptic curve asymmetric algorithm used to sign webhooks. It is similar to RSA, except the key sizes are smaller yet more secure. () to sign webhooks with our private key. You should verify these webhooks using our public key.

: eyJhbGciOiJIUzI1NiJ9.eyJrIjoiYXNkZiIsImIiOiI1MzE0MiIsImMiOiIxMjNhc2RmOCIsImQiOnsiYyI6ImFzZGYiLCJkIjp7ImsiOiJhc2RmIn19fQ.VZrjXoiD_044VXQvPiO_Tk_hNbaIdnSyjfTwsA2oL8I


const jwt = require('jsonwebtoken');

// Our public key found at https://api.transcend.io/public-keys/transcend-webhook-signing-key
const TRANSCEND_PUBLIC_KEY = '-----BEGIN PUBLIC KEY-----\nMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAErvJoVVdxiJpRu/euANrx3LXLPmxAnNxB\n0r/p1If6S8ViW1Eif6whMrkGi+BVBNf6MKqNxmzPlWQJzie4YI6s1YWaBj9vWqlG\n14uhO0iB63cU/yecYT67FIY5DVH9sH0F\n-----END PUBLIC KEY-----\n';

/**
 * Verify a webhook from Transcend using jwsonwebtoken module
 */
function verifyTranscendWebhook(req, res, next) {
  // Get the token
  const token = req.headers[''];

  // Test the signature
  jwt.verify(token, TRANSCEND_PUBLIC_KEY, {
    algorithms: [''], // it's important that you whitelist ES384
  }, (error, body) => {
    // The signature could not be validated
    if (error) {
      next(new Error('The token signature was invalid'));
    }

    // You can now trust the decoded content
    res.locals.trustedJWTContent = body;
    next();
  });

}

Security Tip: Always whitelist algorithms when using a JWT library

When using a JWT library, make sure you always whitelist the algorithms you allow. You should never let the token define what algorithm it should use to decode itself.

Reading our public key

You can get our current public key at the following URLs:

PEM Format

We host a PEM file at https://api.transcend.io/public-keys/transcend-webhook-signing-key that your server can issue a GET request to.

JSON Web Keys

We also store our webhook signing key using the JWK standard. You can find all of our public keys at https://api.transcend.io/.well-known/jwks.json. The kid we use to sign webhooks is transcend-webhook-signing-key

Public key caching and storage

We recommend caching our public key for about 1 day. You can also save our public key locally, in which case you will need to manually change the key when we change it (we'll notify you when we do). If Transcend receives a 401 from your server, it will fail gracefully, wait, and retry later.

Identifier Signing

When an identifier is created, we allow the issuer to sign the identifier values using a Json Web Token.

Coming in version 1.2, stay tuned!


Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.