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.
More in-depth instructions and code examples can be found here: https://github.com/templafy/CustomContentConnector
Prerequisites
|
|
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.
|
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)
- response_type (string): “code”
- client_id (string): Client ID from an external app registration and configured in the Templafy Admin Center
- 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
- 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
|
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
- 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 the format: “Bearer ACCESS_TOKEN”
- x-TemplafyUser: Will contain the email address of the current user in the format: "currentuser@example.com"
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/jpg
- image/png
- image/bmp
- image/tif
- image/tiff
- image/x-ms-bmp
- image/svg+xml
- image/gif
- 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”
- x-TemplafyUser: Will contain the email address of the current user in the format: "currentuser@example.com"
URL Path parameters:
- contentId (string): Id of the content
Returns:
- downloadUrl (string): Generated shared access link to the full size content
Response example:
{
"downloadUrl": "https://linktocontent.com/?token=shortlivedsecuretoken"
}
|
Comments
0 comments
Article is closed for comments.