# App integration To access this workflow, the integrating client must provide a JWT as an entry point. This token should contain the clientId, userId (for session impersonation), and an action defining what the session will do before redirecting the user to editor mode. All of this must be signed with the secret. The clientId and secret pair are created in The brief under **Manage account/API credentials.** You can generate the token using the NodeJS script: ```javascript // nodejs import jwt from 'jsonwebtoken'; const clientId = 'yourClientId'; // Replace with your actual clientId const secret = 'yourSecret'; // Replace with your secret key // Create the payload const payload = { clientId, userId, action: { type: "create_blank_design", sizes: [{"width": 111, "height": 111}], projectId: 100, folderId: 111, // this is optional editorMode: "adstudio" } }; // Sign the payload to create a JWT const token = jwt.sign(payload, secret); // Construct the URL const url = `https://app.thebrief.ai/tokenAuth?token=${token}`; console.log(url); ``` Or for testing purposes, you can use a JWT playground like the one from , where you can generate the token manually. To start the session, add the generated token in the The Brief app `https://app.thebrief.ai/tokenAuth?token=${token}`

JWT.IO example

The editor can be embedded in an iframe, too. Here's how: [Iframe embedding](/app-integration/iframe-embedding.md) ## JWT Parameters These are general parameters for starting the JWT token that starts the editor session. > **Parameters for this action:** > > **`clientId`** - (required) The clientId form the API Configuration inside The Brief app (the same that is used to generate bearer token to call APIs requests) > > **`userId`**- (required) the userId for the user you impersonate in the session (if the clientId/secret pair is generated by the team owner or admin, you can impersonate users from your team). > > **`action`**- (required) define the action that this session if started for defined [here](#actions-for-the-session). > > **`sessionConfig`**- usually UI configs for the current session. More on them [here](#session-configuration). ## Actions for the session To start a session, you need to provide an action type. Currently, we support four actions: *create\_design\_from\_template, create\_blank\_design,* *edit\_design*, and *get\_share\_link*. Add the action/type field in the JWT to call these actions. Each action has a set of specific parameters, which are explained for each type below. ```json "action": { "type": "create_design_from_template", } ``` ### Edit design This action will create a new design from an existing one (template). > **Parameters for this action:** > > **`hash`** - The hash of the template (design or custom template) > > **`editorMode`** - Which editor to open in the session ("adStudio" or "light-editor") ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "edit_design", "hash": "template-hash", "editorMode": "adstudio" | "light-editor" } } ``` ### Create a design from a template This action will create a new design from an already existing design (template). > **Parameters for this action:** > > **`hash`** - The hash of the template (design or custom template) > > **`name`** - The name I want the design to have (Optional) > > **`projectId`** - ID of the project in which we want this design to be created > > **`folderId`** - ID of the folder in which we want this design to be created (optional) > > **`editorMode`** - Which editor to open in the session ("adStudio" or "light-editor") ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "create_design_from_template", "name": "My design name", "hash": "template-hash", "projectId": your-project-id, "folderId": your-folder-id, // this is optional "editorMode": "adstudio" | "light-editor" } } ``` ### Create a blank design This action will create a new blank design. > **Parameters for this action:** > > **`sizes`** - An array of sizes for the design > > **`customSizes`** - An array of custom sizes (note: you can only provide either **`sizes`** or **`customSizes`** not both) > > **`name`** - The name I want the design to have (Optional) > > **`projectId`** - ID of the project where the design will be created > > **`folderId`** - ID of the folder where the design will be created (optional) > > **`editorMode`** - Editor to open in the session ("adStudio" only) **An Example using the sizes parameter** ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "create_blank_design", "name": "My design", "sizes": [{"width": 111, "height": 111}], "projectId": your-project-id, "folderId": your-folder-id, // this is optional "editorMode": "adstudio" } } ``` **An Example using the customSizes parameter**
`customSizes` gives you the ability to name your sizes while you're creating your design ``` { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "create_blank_design", "name": "My design", "customSizes": [{"width": 400, "height": 600, "name": "Facebook size"}], "projectId": your-project-id, "folderId": your-folder-id, // this is optional "editorMode": "adstudio" } } ``` ### Get the share link This action will get you the shared link for a design or a folder based on the provided parameters. If you give a `designHash`, you will get a shared link for a design. And, if you give a `folderId`, you will get a shared link for a folder. One of these parameters must be provided.\ This action now supports an optional parameter, `openRightBar`, to provide additional functionality for the share link page. > **Parameters for this action:** > > **`designHash`** - The hash of the design that you want its share link (could be `undefined` if you provide `folderId`) > > **`folderId`** - The id of the folder that you want its share link (could be `undefined` if you provide `designHash`) > > **`openRightBar`**- If `true`, opens the comments panel on the share link page. Has no effect if `useShareLinkComments` in the `sessionConfig` is disabled. (this param is optional and its default value is `false`) ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "get_share_link", "designHash": "design-hash", // mandatory for a design share link "folderId": 1234, // mandatory for a folder share link "openRightBar": true // the useShareLinkComments in the sessionConfig should be enabled to use this param } } ``` #### Behavior of openRightBar Param * If the parameter `openRightBar` is set to `true`: * The comments panel will open automatically when the share link page is accessed, provided that `useShareLinkComments` in the `sessionConfig` is enabled. * If `useShareLinkComments` If this parameter is disabled, this parameter will be ignored, and the comments panel will not be displayed. * When `openRightBar` it is omitted or set to `false`, the comments panel will remain closed by default. ### Flow: Create from URL (BETA) This action will start the flow of creating a design from a URL using AI > **Parameters for this action:** > > **`projectId`** - ID of the project where the design will be created > > **`folderId`** - ID of the folder where the design will be created (optional) > > **`name`** - The name I want the design to have (Optional) > > **`brandkitId`** - Brand Kit ID: Specifies the Brand Kit where assets will be uploaded. In this flow, only assets and templates associated with this Brand Kit will be accessible. (Optional) > > **`redirectURL`** - At the end of the creation flow will be redirecting to this URL (Optional) ```json { "type": "nextgen_flow_create_from_url", "projectId": 100, "folderId": 124, // this param is optional "name": "Test design name", // this param is optional "brandkitId": 124 // this param is optional "redirectUrl": "www.google.com" // this param is optional } ``` ### Flow: Create from a template (BETA) This action will start the flow of creating a design from the template > **Parameters for this action:** > > **`projectId`** - ID of the project where the design will be created > > **`folderId`** - ID of the folder where the design will be created (optional) > > **`name`** - The name I want the design to have (Optional) > > **`brandkitId`** - Only templates within that Brand Kit will be displayed. (Optional) ```json { "type": "nextgen_flow_create_from_template", "projectId": 100, "folderId": 124, // this param is optional "name": "Test design name", // this param is optional "brandkitId": 124 // this param is optional } ``` ### Flow: Create from assets (BETA) This action will start the flow of creating a design from assets (logo, images, etc.) > **Parameters for this action:** > > **`projectId`** - ID of the project where the design will be created > > **`folderId`** - ID of the folder where the design will be created (optional) > > **`name`** - The name I want the design to have (Optional) > > **`brandkitId`** - Only assets within that Brand Kit will be displayed. (Optional) ```json { "type": "nextgen_flow_create_from_assets", "projectId": 100, "folderId": 124, // this param is optional "name": "Test design name", // this param is optional "brandkitId": 124 // this param is optional } ``` ## Session Configuration The `sessionConfig` object allows users to customize their white-label session by enabling or disabling certain features like design download, share link, and comments. By providing this configuration in their JWT token, end users can control session behavior based on their specific needs. ### Object Structure ```json { "sessionConfig": { "useDownload": false, "useAdServing": false, "usePublishToMeta": false, "usePublishToGoogleAds": false, "useShareButton": true, "useShareLinkComments": true, "useAiEditText": false, "useAiEditImage": true, "useAiTranslate": false, "brandkitIds": [1, 2, 3], "hideToolbarItems": ["templates", "elements"], "hideAllToolbarItemsExcept": null } } ``` ### Properties
PropertyTypeDefaultRequiredDescription
useDownloadBooleanfalseNoEnables or disables the option to download design within the session. If true, download functionality is available; if false, it is disabled.
useShareLinkCommentsBooleanfalseNoEnables or disables the option to add comments to share links within the session. If true, comments are allowed; if false, they are not.
useShareButtonBooleantrueNoEnables or disables the option to use the share button. if true the share button appears, if false, the share button is hidden
useAiEditTextBooleantrueNoEnables or disables the usage of editing text using AI. if true this option is enabled and if false it's disabled
useAiEditImageBooleantrueNoEnables or disables the usage of editing image using AI. if true this option is enabled and if false it's disabled
useAiTranslateBooleantrueNoEnables or disables the usage of translation using AI. if true this option is enabled and if false it's disabled
useAdServingBooleanfalseNoEnables or disables the usage of Ad Serving. if true this option is enabled and if false it's disabled
usePublishToMetaBooleanfalseNoEnables or disables publishing to Meta. if true this option is enabled and if false it's disabled
brandkitIdsArray of Brandkit Ids[]NoGives you the control to limit the brandkits that are shown in AdStudio. If it's not provided, the brandkits available will depand on the brand control defined on team and project level
### Usage To configure these session options, include the `sessionConfig` object in the payload of your JWT token. This configuration will then be applied to the session. ```json { "clientId": "YOUR-CLIENT_ID", "userId": userId, "action": { "type": "edit_design", "hash": "template-hash", "editorMode": "adstudio" | "genstudio" }, "sessionConfig": { "useDownload": false, "useShareLinkComments": true, "useShareButton": true, "useAiEditText": false, "useAiEditImage": true, "useAiTranslate": false, "useAdServing": true, "usePublishToMeta": false, "brandkitIds": [123, 456] } } ``` In this example: * `useDownload: false` disables downloads for the session. * `useShareLinkComments: true` enables comments on shared links. * The share button is active (`useShareButton: true`). * AI-powered text editing is disabled (`useAiEditText: false`), while AI image editing is enabled (`useAiEditImage: true`). * AI translation is disabled (`useAiTranslate: false`). * Ad serving is active (`useAdServing: true`). * Publish to Meta is disabled (`usePublishToMeta: false` ). * Brand-specific configurations are applied based on `brandkitIds`. #### Notes * **Optional Properties**: All properties in the `sessionConfig` object are optional. If not provided, default values will apply. * You can start your session without the `sessionConfig` provided, the default values will also be applied in this case. * **Brand Kit Support**: If `brandkitIds` is not specified or is an empty array, no brand-specific configurations will be applied. ### Supported Toolbar Items (`Tools`) The following toolbar items can be specified for `hideToolbarItems` or `hideAllToolbarItemsExcept`: * `"templates"` * `"elements"` * `"brandKit"` * `"layers"` * `"slides"` * `"animator"` * `"feedTool"` * `"apps"` * `"resize"` * `"help"` ### Usage Rules for Toolbar Configuration 1. **Mutual Exclusivity**: The parameters `hideToolbarItems` and `hideAllToolbarItemsExcept` are mutually exclusive. You cannot use both at the same time. If both are provided, the session will fail to load the configuration. 2. **Functionality**: * **`hideToolbarItems`**: Specifies toolbar items to be removed from the left toolbar. * **`hideAllToolbarItemsExcept`**: Specifies toolbar items to remain visible, removing all others. ### Examples **Example 1: Hiding Specific Toolbar Items** To hide only the `"templates"` and `"elements"` toolbar items: ```json jsonCopy code{ "sessionConfig": { "hideToolbarItems": ["templates", "elements"] } } ``` **Example 2: Keeping Specific Toolbar Items Visible** To hide all toolbar items except `"templates"` and `"elements"`: ```json jsonCopy code{ "sessionConfig": { "hideAllToolbarItemsExcept": ["templates", "elements"] } } ``` #### Notes 1. **Empty Arrays**: Providing an empty array for `hideToolbarItems` or `hideAllToolbarItemsExcept` will result in no changes to the toolbar. 2. **Priority**: Ensure only one of `hideToolbarItems` or `hideAllToolbarItemsExcept` is included to avoid conflicts. 3. **User Experience**: Consider the user's workflow before hiding or limiting access to toolbar items to ensure functionality aligns with their needs. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.thebrief.ai/app-integration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.