Signed URL API

For the basic usage of parameters please see the URL API Reference. This page is about implementing the Signature to secure Requests to the URL Api.

Overview

Signing the URL works by appending a signature URL Parameter to the existing URL API Request which is a SHA-256 Hash of your existing URL API Request URL and your API Token.

It secures the URL from manipulation by malicious actors. If you are showing the URL to third-parties (users, public-web, etc.) you should always use the Signed URL API

Don't sign client side

Do not generate the signature for the Signed URL API on the client side, as you need the API key for it.

Generating an API Key

You can get an API Key via the API Keys Page. API Keys have access to all the projects and templates of your team.

Sign the URL

To create the signature hash, create SHA-256 Hash of your existing URL API Request URL contaccted your API Token

SHA256 ( URL_API_REQUEST_URL + API_TOKEN )

See the example implementations below:

PHP Example

If you do use composer, you can install the mediamask composer package.

composer require mediamaskio/mediamask-php

getSignedUrl() and API Calls

Calling the ->getSignedUrl() method will not send an API call, it only creates a signed URL locally, using your API Key. The image renders only when the URL is first accessed

and use the ->getSignedUrl() function like this

$config = \Mediamask\Configuration::getDefaultConfiguration()
    ->setAccessToken('API_TOKEN');
$apiInstance = new \Mediamask\Api\MediamaskApi(
    new \GuzzleHttp\Client(),
    $config
);
$parameters = array(
    'title' => 'Headline',
    'background' => 'https://mediamask.io/background.jpg',
);


$signedImageUrl = $apiInstance->getSignedUrl($templateId, $parameters);

Node.js Example

To use mediamask within Node.js you can install the mediamask npm package.

npm install mediamask-js

After initializing the Mediamask API Client with your API Token, you can use the createSignedUrl() function to create a signed URL.

Make sure to replace the API_TOKEN with your API Token and TEMPLATE_UID with the Template UID of your template.

import { MediamaskApi, Configuration } from 'mediamask-js';


const api = new MediamaskApi(
  new Configuration({
    accessToken: 'API_TOKEN',
  })
);


const signedUrl = api.createSignedUrl('TEMPLATE_UID', {
    title: 'What a great title',
    background_image: 'https://mediamask.io/background.jpg'
});


console.log(signedUrl);

Python Example

from urllib.parse import urlparse, urlencode, urlunparse
from hashlib import sha256


args_dict = {'title': 'Headline', 'background': 'https://mediamask.io/background.jpg'}
base_url = 'https://mediamask.io/'
path = '{ TYPE IN YOUR TEMPLATE UID HERE }'
apiKey = '{ TYPE IN YOUR API KEY HERE }'


# Generate URL API Request URL
url_parts = list(urlparse(base_url))
url_parts[2] = 'image/' + path
url_parts[4] = urlencode(args_dict)
urlApiRequest = urlunparse(url_parts) + apiKey


# Generate Signed URL
signature = sha256(urlApiRequest.encode('utf-8')).hexdigest()
args_dict["signature"] = signature
url_parts[4] = urlencode(args_dict)
signedurlApiRequest = urlunparse(url_parts)


print(signedurlApiRequest)