Guides
By default, content fields outside of the content namespace are read-only via the Frontend API. In cases where you want your models and fields to display content and utilize business logic in a storefront, you’ll need to open the permissions.
For instance, let’s say that you want to integrate a fee system to your Swell store. This system will generate fees and apply them to orders using the Backend API. In the case where you want to display these fees to customers on the frontend, you will need to open the field’s permissions to get Frontend API access.
Field rules set which fields the Frontend API returns and accepts. The store's rules apply to every public key in an environment, including keys created later, and to requests made without a key. Each environment has its own rules, so rules saved in the test environment don't affect live. Secret keys aren't affected.
In the new Swell dashboard, go to Developer › API keys › Field access to edit the store's rules for the current environment. For each model, Block hides fields, and Allow makes more fields public on top of the model's default public fields. Saving a rule that makes fields public asks for confirmation first. The classic dashboard has no Field access page, so set the rules through the Backend API.
The store's rules are stored in public_permissions at /:clients/:self, by environment (live or test), then by model. Each model's rule has the same shape as a public key's permissions:
| Property | Description |
| fields | Fields the Frontend API returns, in addition to the model's defaults. Nested fields use dot notation, such as images.caption. |
| input.fields | Fields the Frontend API accepts in writes, in addition to the model's defaults. |
| hidden | Field names removed from Frontend API responses. A hidden name is removed at any depth, from every model in the response. Reads of the model whose input mentions a hidden field, for example in a filter or a sort, are refused. |
| query | Filter that replaces the model's default filter. Products default to active: true, so a query without it also returns inactive products. Set through the API only. |
| expands | Expandable fields by name, merged with the model's defaults. Set through the API only. |
{
"$set": {
"public_permissions": {
"live": {
"products": {
"fields": ["warranty"],
"hidden": ["stock_level"]
}
},
"test": {}
}
}
}In this example, a PUT to /:clients/:self makes the products' warranty field public in live, and removes stock_level from live responses. The test environment has no rules.
Save rules with $set. It replaces the whole public_permissions object, so read it first and include the rules of every environment. Without $set, the API merges the request into the saved rules, and a shorter list doesn't remove fields.
A public key's own permissions override the store's rules on that key. A key's entry for a model replaces the store's rule for that model, and an empty entry ({}) gives the key only the model's defaults. In the new Swell dashboard, choose Field access in the key's menu on the API keys page. Through the Backend API, follow these steps, and send the key's permissions with $set to replace its rules instead of adding to them.
Choose a public key
Go to Developer → Console on the dashboard and make a GET request to /:clients and enter /:self/keys/ in the URI. In the response, find the current public key you wish to use and copy its id.
Make fields readable
Make a PUT request to /:clients and enter /:self/keys/<id_from_previous_step> in the URI field. In the console body, execute the following JSON to establish public read access.
{
"permissions": {
"<model_name_to_configure>": {
"fields": ["<field_to_add_read_access>"]
}
}
}Make fields writable
Edit the content field’s permissions by adding write access.
{
"permissions": {
"<model_name_to_configure>": {
"input": {
"fields": ["<field_to_add_write_access>"]
}
}
}
}That's all there is to it. You’ve successfully opened the content model and field’s permissions for Frontend API access.
Content fields can be made writable by use of input.fields.
"input": {
"fields": [
"billing",
"billing_schedule",
"cancel_at_end",
"canceled",
"coupon_code",
"date_pause_end",
"items.id",
"items.options",
"items.product_id",
"items.quantity",
"items.variant_id",
"options",
"paused",
"plan_id",
"product_id",
"quantity",
"shipping",
"variant_id"
]
}Additionally, records can be limited to a logged-in account (where account_id = current user)
"scope": "account"