Tokens

Imagine you have built a clothing store. You want the products you registered in the content studio to be pulled in and shown on the storefront site that your customers see. But that site is a program, not a person. It cannot log in with an ID and password the way a person does. A token is the secret key you issue so that a site or program can access your content in place of a person.

Think of a token as a single key that opens a lock. Whoever holds this key can work with content within a set scope, without logging in. That is why a token must be handled exactly like a password. You should not show it to just anyone, and if it leaks, whoever holds it can use that same access.

WEEGLOO has two kinds of keys for different purposes. One is a powerful key tied to an account (Personal Access Token), and the other is a narrow key for reading content out to a public site (Delivery Access Token). On this page you will look at what each key is and when to use it, then issue them yourself in the content studio.

The two keys serve different purposes

Here is a side-by-side look at how they differ.

The key point is this. A Personal Access Token is close to a master key that stands in for one person, while a Delivery Access Token is a narrow key that "can only see the bulletin board at the front door." Their uses do not overlap, so pick the one that fits what you are trying to do.

A key tied to an account: Personal Access Token

A Personal Access Token is a key tied to the account that issued it. With this key, you can do everything that account can do in the content studio, without logging in. That includes management work such as registering products, editing them, and publishing them.

That is what makes this key powerful. For example, if you build a program that automatically uploads new products to the content studio every night, that program cannot log in like a person, so you hand it this key. It is the key you use to run management work automatically in places not directly visible to people, such as servers and automation scripts.

Because it is powerful, it needs to be handled with care. Do not put this key into a public website that customers see, or into a browser. If you put it somewhere public, anyone can pull the key out, and whoever gets hold of it can use the issuing account's permissions as-is. When you only need to pull in products and show them on a public site, use the Delivery Access Token below instead of this powerful key.

For a Personal Access Token, you only set a name when you issue it. You do not choose a permission scope separately, because it inherits the permissions the issuing account already has.

A key tied to a Space: Delivery Access Token

A Delivery Access Token is a read-only key tied to one specific Space. With this key you can only read content that is in the Published state within that Space. Content in the Draft state that has not been published cannot be read with this key, and you cannot edit or delete anything either.

This is exactly the key that the storefront site uses when it pulls in products and shows them to customers. The site only needs to display products, not register or delete them, so a narrow key that can only read is enough. Even if this key leaks, only published content can be read with it, and it cannot damage your content.

What it means to publish (Published) content, and why content must be published before it is delivered externally, is covered in States and Publishing.

Bind a narrow role to limit what it can read

When you issue a Delivery Access Token, you set how far this key can read with a SpaceRole and bind it to the key. A role is a permission bundle that defines "what can be done, and with which actions." When you bind a role to a key, that key can read only as much as the bound role allows.

For a storefront site, you only need to read "products," so create a narrow role that allows only Read on products (Content) and bind it. That way, even if this key leaks, only product information can be read, and other content or member information does not leak with it.

Do not bind the Administrator role, which can handle everything. Administrator is the highest-privilege role that can handle everything in that Space. Binding such broad access to a key for a public site that only needs to read raises the risk if the key leaks. It is safer to create a separate role narrowed down to read only what is needed and bind that.

How to create roles and narrow permissions is covered in Roles and Permissions. Use that page to create, in advance, the role that allows only product Read, to be bound to your public-site key.

Handling the issued secret value

For both keys, once issuing is finished, a secret token value appears on the screen. That value is the key itself. You use this value when you put it into a server or site. Copy it on the spot right after issuing and store it. You can also check it again on the token's detail screen.

The two keys, however, belong in different places.

• Handle a Personal Access Token like a password. Because it is a powerful key, keep it only inside a server, and do not put it into a public site that customers see, into a browser, or into code that others can view.
• A Delivery Access Token, on the other hand, is meant to be placed into a public site that customers see. Anyone who opens the site can effectively see this value, but because you have bound a narrow role to it, even if someone takes the value they cannot do anything beyond the read scope that role allows. So putting it into the site itself is not a problem. Just do not spread it carelessly outside the site where you intend to use it.

If you lose a key, or it seems to be used in a way you did not intend, you can delete that key, issue a new one, and swap it in.

Issuing a Personal Access Token

Issue a Personal Access Token to hand to the program that automatically uploads new products every night.

1. Open the Personal Access Token screen in your account settings.
2. Press the Create button at the top right.
3. Enter Nightly New Arrivals Upload in the name field. This name is so you can later tell what purpose the key was made for.
4. Press the Save button to issue it.

Once issuing is finished, the secret token value appears on the screen. Copy it on the spot and store it somewhere safe. The screen looks the same as the Delivery Access Token issue result below.

Issuing a Delivery Access Token

This time, issue a Delivery Access Token for the storefront site to use when it pulls in products and shows them. This key is tied to the clothing store Space, and you bind it together with a narrow role that can read products.

First, the role to bind to this key must already exist in the Space. Use Roles and Permissions to create, in advance, a role that allows only Read on products (Content). Below, assume you have created that role under the name Product Read-only.

1. Open the Delivery Access Token screen in the settings of the clothing store Space.
2. Press the Create button at the top right.
3. Enter Storefront site delivery in the name field.
4. In the description field, you can note what this key is used for. (This is optional.)
5. In Space Role, choose Product Read-only. Do not choose Administrator.
6. Press the Create button to issue it.

Once issuing is finished, the secret token value appears on the screen. Copy it on the spot and store it somewhere safe.

Delete keys you no longer use

It is safer to delete a key you have stopped using rather than leaving it in place. Find the key you no longer use in the token list and delete it. Once you delete a key, it can no longer be used for access. The same goes when a key seems to have leaked. Delete the suspect key, issue a new one, and swap it in.

What to do next

• Roles and Permissions: Create the role with a narrowed read scope to bind to a Delivery Access Token.
• States and Publishing: A Delivery Access Token reads only content in the Published state. Learn what publishing is.
• API Reference: Covers technical specifications such as the request format needed when you issue tokens or pull in content directly from a program.