令牌

假设您开了一家服装网店。您想把已经登记在内容工作室里的商品，调取出来展示在顾客看到的购物网站上。但那个网站不是人，而是程序。它无法像人一样用账号和密码登录。这时，为了让网站或程序代替人来访问内容而签发的秘密钥匙，就是令牌。

可以把令牌想象成一把开锁的钥匙。持有这把钥匙的一方，即使不登录，也能在规定的范围内处理内容。因此令牌要像密码一样对待。它不能随便给人看，一旦泄露，拿到它的人就能照样使用那份权限。

WEEGLOO 提供三种用途不同的钥匙。一种是代替整个账号的强力钥匙（Personal Access Token），一种是在一个 Space 内读写内容的钥匙（Space Access Token），还有一种是为了把内容读取并送往公开网站的只读钥匙（Delivery Access Token）。本页先了解这三把钥匙各是什么、何时使用，然后在内容工作室里亲手签发一次。

三把钥匙用途不同

先把三者的区别一目了然地整理如下。

核心是这样的。Personal Access Token 更接近一把整个代替某个账号的人的万能钥匙；Space Access Token 是一把只在一个 Space 内读写内容的钥匙；Delivery Access Token 则是一把只把已发布内容读取出来的只读钥匙。按照要做的事是横跨整个账号、是在一个 Space 内还要写入、还是只在公开网站读取，挑对应的那把钥匙即可。

代替整个账号的钥匙：Personal Access Token

Personal Access Token 是一把原样使用签发它的账号本人权限的钥匙。用这把钥匙，就能不登录而照样做那个账号在内容工作室里能做的事。包括登记商品、修改商品，乃至发布这样的管理操作都可以。

正因如此，这把钥匙很强力。把它交给一个代替人自动上传和修改内容的程序，那个程序就能像账号主人一样工作。如果是需要在多个 Space 之间往来、乃至处理 Space 设置的管理操作，就需要这把钥匙。反过来，如果只需在一个 Space 内读写内容，那么与其用这把代替整个账号的钥匙，不如用后面介绍的 Space Access Token 把权限收窄，会更安全。

越强力，使用时越需要格外小心。这把钥匙不能放进传递给顾客的公开客户端里。 因为一旦放在公开的地方，任何人都能把钥匙取出来看，而拿到这把钥匙的人就能照样使用签发账号的权限。当只是要在公开网站调取并展示商品时，不用这把强力的钥匙，而用下面的 Delivery Access Token。

Personal Access Token 在签发时只需定个名称即可。无需另行挑选权限范围。因为它会原样继承签发账号所拥有的权限。

在一个 Space 内读写的钥匙：Space Access Token

Space Access Token 是一把只在某一个特定 Space 内使用的钥匙。与 Delivery Access Token 只能读取不同，用这把钥匙不仅能读取那个 Space 内的内容，还能写入。登记新商品或修改商品这类工作，即使人不登录，也能由程序代为完成。

比如，假设您想让顾客不登录也能在服装店网站上留下咨询留言。顾客使用的客户端需要把那条留言新写入服装店的 Space，而只读的 Delivery Access Token 无法写入。可要是把代替整个账号的 Personal Access Token 放进客户端，那么这把钥匙一旦泄露，不只是服装店，账号所触及的一切地方都会陷入危险。这时用的，就是只在一个 Space 内也能写入的 Space Access Token。让顾客客户端写入内容的这类情况是这把钥匙的代表性用途，在服务器上自动登记、修改内容时也会用到。

Space Access Token 只在一个 Space 内发挥作用。它虽然能读写服装店 Space 的内容，却无法窥看其他 Space、更改 Space 的设置，也无法触及组织和账号。因此即便同样是写入操作，它也比 Personal Access Token 更安全。

这把钥匙放在哪里，取决于用途。可以放在服务器上，也可以放在顾客使用的客户端上。安全并不靠把钥匙藏在某处，而是靠按用途收窄所绑定的角色来守护。因此接下来，如何绑定角色就很重要。

绑定角色来规定可读写的范围

签发 Space Access Token 时，同样要用 SpaceRole（角色）来规定这把钥匙能做到哪里，并一同绑定。与 Delivery Access Token 的角色规定"能读到哪里"不同，Space Access Token 的角色规定的是"能读写到哪里"。

所绑定的角色，要按这把钥匙放在何处来收窄。如果是在服务器上自动登记、修改商品的钥匙，就绑定一个对商品（Content）只允许 Read、Create、Edit，而不放入 Delete、Publish 的角色。反之，如果是放在顾客客户端、只用来接收咨询留言的钥匙，就绑定一个只允许新建"咨询留言"（Create）的更窄的角色。这样一来，即使这个值泄露，也无法在各自允许的范围之外做任何事。

请不要绑定能处理一切的 Administrator 角色。 越是连写入都能做的钥匙，尤其是放在顾客能看到的地方的钥匙，越要绑定一个即使泄露也能承受的窄范围角色，才安全。

创建允许写入的角色的方法，将在角色与权限中介绍。那一页中创建的"商品上架负责"角色，就是一个允许登记、修改商品的写入用角色的例子。

在一个 Space 内只读的钥匙：Delivery Access Token

Delivery Access Token 是一把只在某一个特定 Space 内通行的只读钥匙。用这把钥匙，只能读取那个 Space 内处于 Published（发布）状态的内容。尚未发布、处于 Draft 状态的内容用这把钥匙读不到，也无法修改或删除。

顾客看到的购物网站在调取并展示商品时使用的，正是这把钥匙。网站只需展示商品，无需登记或删除，所以一把只能读取的窄范围钥匙就足够了。即使这把钥匙泄露，也只是已发布的内容会被读到，无法破坏内容。

把内容发布（Published）是什么意思，以及为什么必须发布才会对外公开（传递），将在状态与发布中介绍。

绑定窄范围的角色来限制可读范围

签发 Delivery Access Token 时，要用 SpaceRole（角色）来规定这把钥匙能读到哪里，并一同绑定。角色是一份预先定好"能对什么、做到什么动作"的权限组合。给钥匙绑定角色后，这把钥匙就只能在所绑定角色允许的范围内读取。

如果是购物网站，只需读取"商品"即可，所以创建一个对商品（Content）只允许 Read 的窄范围角色并绑定。这样即使这把钥匙泄露，也只是商品信息会被读到，其他内容或成员信息都不会泄露。

不要绑定能处理一切的 Administrator 角色。 Administrator 是那个 Space 内能处理一切的最高权限角色。给只需读取的公开网站用钥匙绑定这么宽的权限，钥匙一旦泄露，风险就会变大。另行创建一个只收窄到读取所需内容的角色再绑定，才更安全。

创建角色并收窄权限的方法，将在角色与权限中介绍。请对照那一页，预先创建好一个只允许读取商品的角色，供公开网站用钥匙绑定。

用允许的 Referrer 规定能使用这把钥匙的网站

如果说所绑定的角色规定了用这把钥匙能读什么，那么允许的 Referrer 规定的是这把钥匙能在哪里使用。这项设置在创建页面的下方，签发之后也可以更改。

初始值是不限制。在这个状态下，不论从哪个网站调取，内容都会传递过去。选择仅允许指定的 referrer 后，会出现填写地址的输入框，从那时起，只有来自这里所填地址的请求才能通过。如果服装网店的地址是 https://shop.example.com，就把这个地址填进去。这样一来，即使这把钥匙的值落到别人手里，在服装店网站之外也不管用。

地址可以填写多个。点击添加按钮，就会再多出一个输入框；点击输入框右侧的删除图标，那一行就会消失。

如果想把挂在 shop.example.com 下面的地址一并允许，就在最前面加上 *.，写成 https://*.shop.example.com 这样。这样填写会把 event.shop.example.com 这类前面带有其他部分的地址全部包含进来。不过即使这样填写，https://shop.example.com 本身也不包含在内。如果两者都要允许，请把 https://shop.example.com 也另填一行。

这个列表是按照顾客在浏览器中打开网站并调取内容的情形来运作的。如果使用这把钥匙的不是网站，而是在服务器上运行的程序，那就无法知道请求来自哪个网站，所以这类钥匙请保持不限制不变。

处理签发出的秘密值

三把钥匙都一样，签发完成后就会进入那把钥匙的详情页面。基本信息的 Token 栏里放着秘密令牌值，点击栏位左侧的复制按钮就会复制整个值。值比栏位长，所以页面上看到的是后半部分被截断的样子，但复制的是完整的值。这个值本身就是钥匙，把钥匙放进服务器或网站时用的就是这个值。即使签发后没有当场复制，之后也可以再次进入这个详情页面复制。右侧面板 Token 项中的 ID 是指向这把钥匙的标识符，不是秘密值。

不过每把钥匙存放的地方不同。

• Personal Access Token 请像密码一样对待。因为它是强力的钥匙，所以只放在服务器内部，不要放进顾客看到的公开客户端，或别人能看到的代码里。
• Space Access Token 放在哪里，靠所绑定的角色来配合。放在服务器上的钥匙，绑定一个够用的写入角色；放在传递给顾客的客户端上的钥匙，则绑定一个即使泄露也能承受的窄范围角色（例如只新建某一种帖子）。不要把 Administrator 或范围宽泛的写入角色绑定到放在公开位置的钥匙上。
• Delivery Access Token 则相反，放进顾客看到的公开网站正是它本来的用途。打开网站的人虽然人人都能看到这个值，但由于已绑定了窄范围的角色，不论谁拿走这个值，都无法在该角色允许的读取范围之外做任何事。所以把它放进网站本身并不会造成问题。如果再用允许的 Referrer把购物网站的地址也填上，那么即使这个值落到别人手里，在那个网站之外也用不了。只是请不要把它随意散播到要使用的网站之外。

如果钥匙丢失了，或似乎被以非本意的方式使用了，把那把钥匙删除并重新签发一把换上即可。

签发 Personal Access Token

下面来签发一把要交给每晚自动上传新品的程序的 Personal Access Token。

1. 在账号设置中打开 Personal Access Token 页面。
2. 点击右上角的创建按钮。
3. 在名称栏里输入 夜间新品上传。这个名称是为了日后辨认这把钥匙是做什么用的。
4. 点击保存按钮完成签发。

签发结束后就会进入那把钥匙的详情页面。请按处理签发出的秘密值中说明的方法，在这个页面复制秘密令牌值，并保管到运行这个程序的服务器上的安全位置。

签发 Space Access Token

这次来签发一把要给服务器使用的 Space Access Token，这台服务器会向服装店 Space 自动登记商品。这把钥匙用在服装店 Space 上，并一同绑定一个能登记、修改商品的角色。

首先，这把钥匙要绑定的角色必须已存在于 Space 中。请先在角色与权限中创建好一个能对商品（Content）进行 Read、Create、Edit 的角色。下面假设已把那个角色以 商品上架负责 这个名称创建好了。

签发与管理的页面，与 Delivery Access Token 位于同一个 Space 设置中。

1. 在服装店 Space 的设置中打开 Space Access Token 页面。
2. 点击列表右上角的创建按钮。Space Access Token 的创建页面就会打开。
3. 在名称栏里输入 新品自动上架服务器。
4. 在 SpaceRole 中选择 商品上架负责。请不要选 Administrator。
5. 允许的 Referrer 请保持不限制不变。因为这把钥匙不是用在网站上，而是用在服务器上。
6. 点击页面右上角的创建按钮完成签发。

签发结束后就会进入那把钥匙的详情页面。请按处理签发出的秘密值中说明的方法，在这个页面复制秘密令牌值并保管到安全的地方。这里绑定的是一个能登记、修改商品的角色，所以这把钥匙用在需要该角色的服务器上。如果必须直接放在顾客使用的客户端上，请另行签发一把绑定了更窄范围角色（即使泄露也能承受）的钥匙来用。对于这样交到顾客手里的钥匙，还请在允许的 Referrer中把那个网站的地址也填上。

签发 Delivery Access Token

这次来签发一把购物网站调取并展示商品时要用的 Delivery Access Token。这把钥匙绑定在服装店的 Space 上，并一同绑定一个能读取商品的窄范围角色。

首先，这把钥匙要绑定的角色必须已存在于 Space 中。请先在角色与权限中创建好一个对商品（Content）只允许 Read 的角色。下面假设已把那个角色以 商品只读 这个名称创建好了。

1. 在服装店 Space 的设置中打开 Delivery Access Token 页面。

2. 点击列表右上角的创建按钮。Delivery Access Token 的创建页面就会打开。

3. 在名称栏里输入 购物网站传递用。

4. 在描述栏里可以写下这把钥匙用在哪里。（可选项。）

5. 在 SpaceRole 中选择 商品只读。请不要选 Administrator。

   

6. 在页面下方的允许的 Referrer 中选择仅允许指定的 referrer。这项设置会限定这把钥匙只能在购物网站上使用。

7. 在出现的输入框里输入 https://shop.example.com。

8. 点击添加按钮。

9. 在新出现的输入框里输入 https://*.shop.example.com。

   

10. 点击页面右上角的创建按钮完成签发。

签发结束后就会进入那把钥匙的详情页面。请按处理签发出的秘密值中说明的方法，在这个页面复制秘密令牌值，放进购物网站里使用。

不再使用的钥匙请删除

不再使用的钥匙，不要放着不管，删除掉才更安全。请在令牌列表中找到不再使用的钥匙并删除。删除钥匙后，就再也无法用那把钥匙访问了。怀疑钥匙泄露时也一样。删除可疑的钥匙，重新签发一把换上即可。

接下来要做的事

• 角色与权限：创建供 Delivery Access Token 绑定的只读角色，以及供 Space Access Token 绑定的读写角色。
• 状态与发布：用 Delivery Access Token 能读到的只有 Published 状态的内容。了解发布是什么。
• Space Access Token：介绍在程序中签发 Space Access Token，或用这把钥匙读写内容时所需的请求格式等技术规格。
• Delivery Access Token：介绍在允许的 Referrer 中填写地址的准确写法规则，以及在程序中处理这把钥匙时所需的请求格式等技术规格。
• API 参考：介绍在程序中签发其他令牌或直接处理内容时所需的请求格式等技术规格。