Aug 15, 2024
Introducing Editor Session
Create a tighter Stencil integration into your webapp using our new Editor Session feature. Create a shareable editor session on the fly with customizable permissions.
Sharleena AM
Technical Writer
Introducing Editor Session
Editor session gives a temporary edit access to your specified template through a shareable link. This is useful and a great way to integrate Stencil right inside your app.
Sessions can be programmatically created using our API, with customizable permissions for each session to meet your specific needs, such as restricting edits to certain layers.
Creating a session
If you’re already familiar with generating image through our API, creating a session should be straightforward as the process is similar. You can also create a session inside your dashboard - please see Managing Sessions section.
To start creating a session programmatically, you will need your project’sAPI_KEY .
Request
Below is the structure of the request, the details are explained later section of this post.
You need to specify the template to create the session for and how long the session should be active before it expires. If you don’t specify the permission, by default users have edit access to all layers.
JSONconst data = {
"template_id": `${TEMPLATE_ID}`,
"expired_in": 60,
"permissions": {
"layers": {
"actions": ["create", "edit"],
"fields": {
"name": "image_1",
"actions": ["edit"]
}
}
}
}
fetch('https://api.usestencil.com/v1/editor/sessions', {
method: 'POST',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
Response
Once a request is sent, an expected response will look something like this.
JSON{
"expired_at": "2024-07-20T19:44:17Z",
"session_url": "https://app.usestencil.com/editor/:template_id/sessions/:session_id?token=xxx"
}
Visit the session_url in a browser to start editing the template.
Request body
| Field | Required | Description |
|---|---|---|
| template_id | Required | Template to give access |
| expired_in | Required | Unit is in minutes. The number of minutes before the session expires. |
| permissions | Optional | Customize the permission for the session. Optional, when not provided the permission defaults to allowing all access. |
For permissions field, please see the next section (Handling permission).
Handling permission
Permission can be customized either during session creation by passing permission options in the API request or you can also edit them using our web application.
For now, we only support layer permission,
Can create layer
Can delete layer
Can edit layer
Customize permission using the API
Layers
There are two fields that you can set with layers.
Layer object
| Field | Required | Description |
|---|---|---|
| actions | Required | Sets the default actions allowable for all layers |
| fields | Optional | allow you to customize the permission for a specific layer. It accepts an array of object that has two fields. |
Field object
| Field | Required | Description |
|---|---|---|
| name | Required | Layer's name |
| actions | Required | List of actions to allow for this layer. Action can be create, edit or delete. |
When fields are specified, it will overwrite the default actions specified.
Examples
JSON"permissions": {
"layers": {
"actions": [],
"fields": {
"name": "image_1",
"actions": ["edit"]
}
}
}
Assuming that you have two layers called image_1 and image_2. In this example, you can only edit the image_1 layer.
You can't edit image_2 layer because the default permissions (set by actions) are set to none. You can't also create a new layer or delete any layers.
Actions
create- Allow new layer creationedit- Allow user to edit the layer settingsdelete- Allow user to delete the layer
Managing sessions
Sessions can be managed through our dashboard where you can view active sessions, revoke access, and adjust settings as needed. This ensures you have full control over who can edit your templates at any given time.
To start managing sessions, under the template’s menu select “Editor Session”.
From the page, you can adjust the session options based on your needs.
You can also create a new session through this page without having to use the API.
Demo
Here’s a session that you can play around. We have changed the permission so that you can only edit the title layer. How neat!
As a bonus, we also embed a form for the template. Once you save the template, try to generate an image based on your changes.
Hope this feature helps with a more intergrated experience using Stencil inside your own application.