Articles in this section

How to build a Custom Content Connector API?

Updated
Follow

About this article

This article will guide you on how to create an API for a Custom Content Connector integration between your internal Digital Asset Management system and Templafy's Library. In other words, such content integration will make it possible to surface images, slides, slide elements, text elements, email elements, and PDFs directly within Templafy Library.

This will make it possible for the images to be widely available right where they are needed when working on your documents, presentations, or emails.

 

Prerequisites

 
  • Admin access in Templafy tenant
  • Admin access in "external system name"
  • Library and connectors modules enabled
  • Content Connector enabled
  • DAM to support Bearer authentication

 

 
  • All the names and values in this article are case sensitive.

 

Step by step guide:

To create a Custom Content Integration, all that must be done is to implement three simple endpoints. The base URL and authentication information are configured in the admin panel, instructions here.

 

Authentication

The Templafy Custom Content Connector allows you to use SSO through an external IdP for authentication. This integration also allows you implement authentication yourself using 3 available authentication types:

The Token Endpoint can be defined as needed. The standard https://example.com/oauth/token is the default in the examples below.

 

Client Credential Flow

POST /oauth/token 

formData:

  • grant_type (string): “client_credentials”
  • client_id (string): Client ID configured in the Templafy Admin Center
  • client_secret (string): Client secret configured in the Templafy Admin Center

 

Returns:

  • Object containing
    • access_token (string): Access token which can be used to access the data in the integration

 

Response example:

{
    "access_token": "3ace249a-29c8-455e-8da9-38047d708cf4",  //example access token
    "token_type": "Bearer",
    "expires_in": 3600
}

 

Authorization Code

More information on using the Authorization Code Flow can be found here.

 
  • The path POST /oauth/token is not a requirement and can be changed.
  • Configuration of this endpoint can either be a relative URL where the endpoint can be used as "base URL + endpoint", or the absolute URL can be defined as the endpoint (and the base URL will be skipped). Defining the endpoint as an absolute URL is useful when an external IdP is used. 

 

Request Authorization Code and Exchange it for tokens 

Authorization Code Flow starts by directing the user to the Authorize endpoint. Once the Authorization code is obtained, it must be exchanged for tokens. 

 

GET /oauth/authorize (configurable)

formData:

 

POST /oauth/token 

formData:

  • grant_type (string): “authorization_code”
  • client_id (string): Client ID from an external app registration and configured in the Templafy Admin Center
  • client_secret (string): Client Secret from an external app registration and configured in the Templafy Admin Center
  • code (string): The authorization code from first step
  • redirect_uri: "https://public.templafy.com/integrations/oauth/login-callback"

Returns:

  • Object containing
    • access_token (string): Access token which can be used to access the data in the integration

Response example:

{
   "access_token": "eyJz93a...k4laUWw",
   "refresh_token": "GEbRxBN...edjnXbL",
   "token_type": "Bearer"
   "expires_in": "300" //in secs, default value is 3600secs/1hr
}

 

Authorization Code with PKCE

More information on using the Authorization Code Flow with PKCE can be found here

 
  • The path POST /oauth/token is not a requirement and can be changed.
  • Configuration of this endpoint can either be a relative URL where the endpoint can be used as "base URL + endpoint", or the absolute URL can be defined as the endpoint (and the base URL will be skipped). Defining the endpoint as an absolute URL is useful when an external IdP is used. 

 

Request Authorization Code and Exchange it for tokens 

Implementation of Authorization Code Flow with PKCE is similar to Authentication Code Flow, with the main difference being the use of a code verifier and a code challenge.

Another difference with this flow is the omission of the Client Secret from the token request. You should not include the Client Secret in your request; the code verifier should be sent instead. This, in combination with the code challenge sent when Authorizing the user, is more secure than sending the Client Secret.

 

GET /oauth/authorize (configurable)

formData:

  • response_type (string): “code”
  • client_id (string): Client ID from an external app registration and configured in the Templafy Admin Center
  • code_challenge (string): Encrypted value of secret code for first login request
  • code_challenge_method: S256
  • scope (string): Optional
  • state (string): "test_tenant"  //tenant id
  • redirect_uri: "https://public.templafy.com/integrations/oauth/login-callback"

POST /oauth/token

formData:
  • grant_type (string): “authorization_code”
  • client_id (string): Client ID from an external app registration and configured in the Templafy Admin Center
  • code_verifier (string): unencrypted value of the code_challenge used in login request
  • code (string): The authorization code from first step
  • redirect_uri: "https://public.templafy.com/integrations/oauth/login-callback"

Returns:

  • Object containing
    • access_token (string): Access token which can be used to access the data in the integration

Response example:

{
   "access_token": "eyJz93a...k4laUWw",
   "refresh_token": "GEbRxBN...edjnXbL",
   "token_type": "Bearer"
   "expires_in": "300" //in secs, default value is 3600secs/1hr
}

 

When using Authorization Code Flow or Authorization Code Flow with PKCE, users will be presented with a login screen. This with Authorize the user and give them user-specific permissions to the assets.

 

Content

GET/content

API endpoint that Templafy will request to the external service in order to get the content of a specific folder (or the root), that should be shown in the Templafy interface. If the external service doesn’t have folders, it’s not needed to return any folders. Any folders should be returned first in the list

 

Header values:

  • Authorization: Will contain the access_token retrieved previously in this format: “Bearer

ACCESS_TOKEN”

 

Query Parameters:

  • contentType (string): Will specify what type of content is being requested. Possible values are image / textElement / slide / slideElement / pdf / emailElement
  • limit (integer): Limits the amount of items to return
  • skip (integer): Skip the first x items, used for paging
  • parentId (string, optional): Id of the parent of which to show content
  • search (string, optional): Content to search for, contains the users search string

 

Returns:

  • contentCount (integer): Total number of results
  • offset (integer): Current offset
  • content: Array of objects containing:
    • id (string): ID of the image
    • mimeType (string): Mime type of the content. Can be of type
      • application/vnd.templafy.folder
      • image/jpeg
      • image/png
      • image/svg+xml
      • application/pdf
      • application/vnd.openxmlformats-officedocument.wordprocessingml.document
      • application/vnd.openxmlformats-officedocument.presentationml.presentation
    • previewUrl (string): Link to a thumbnail size image signed with short life signature. Should be publicly accessible
    • name (string): Name of the asset
    • tags (string): Tags of the asset. Separated by a comma “,”

 

 

Response example:

{
  "contentCount": "32",
  "offset": "12",
  "content": [
    {
      "mimeType": "application/vnd.templafy.folder",
      "name": "Test folder",
      "id": "efjh23j4hjk23h4234"
    },
    {
      "id": "472364786327468723",
      "mimeType": "image/png",
      "name": "Templafy logo.png",
      "previewUrl": "Public SAS link",
      "tags": "Tag1, tag2",
    }
   ]
}

 

Download Content

GET /content/{contentId}/download-url:

API endpoint that Templafy will request to the external service in order to get the download Url of a specific image, which will, then be downloaded by Templafy and given to the user

 

Header values:

  • Authorization: Will contain the access_token retrieved previously in this format: “Bearer

ACCESS_TOKEN”

 

URL Path parameters:

  • contentId (string): Id of the content

 

Returns:

  • downloadUrl (string): Generated shared access link to the full size content

 

Response example:

"https://linktocontent.com/?token=shortlivedsecuretoken"

 

 

 
  • Once the API is ready, in order to finalize the linkage between Templafy and the external DAM, the final configuration must be made in the Templafy Admin center where the Base URL, Client ID, API Key must be specified. See the external related article called "How to configure a Classic Custom Content Connector integration"

 

Related articles

 

Related articles

Comments

0 comments

Article is closed for comments.