GitHub

API references

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);

Without composer

A pure PHP implementation would look like this:

$baseUrl = 'https://mediamask.io/image/';
$templateUid = '{TYPE IN YOUR TEMPLATE UID HERE}';
$parameters = array(
    'title' => 'Headline',
    'background' => 'https://mediamask.io/background.jpg',
);
$apiKey = '{TYPE IN YOUR API KEY HERE}';
    
// Generate URL API Request URL
$urlApiRequest = $baseUrl .
    $templateUid;
    
if(count($parameters) > 0){
    $urlApiRequest .= '?' .
    http_build_query($parameters, null, null, PHP_QUERY_RFC3986);
}


// Generate Signed URL
$signature = hash('sha256', $urlApiRequest . $apiKey);
$parameters['signature'] = $signature;
$signedRequestUrl = $baseUrl .
    $templateUid .
    '?' .
    http_build_query($parameters, null, null, PHP_QUERY_RFC3986);
    
echo $signedRequestUrl;

Node.js Example

const crypto = require('crypto');
const baseUrl = 'https://mediamask.io/image/';
const templateUid = '{TYPE IN YOUR TEMPLATE UID HERE}';
const apiKey = '{TYPE IN YOUR API KEY HERE}';


// Generate URL API Request URL
const requestUrl = new URL(baseUrl + templateUid);
requestUrl.searchParams.set( 'title', 'Headline');
requestUrl.searchParams.set( 'background', 'https://mediamask.io/background.jpg');


// Generate Signed URL
const signature = crypto
    .createHash('sha256')
    .update(requestUrl.toString() + apiKey)
    .digest('hex');
requestUrl.searchParams.set( 'signature', signature);


console.log(requestUrl.toString());

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)
Previous
URL API