In KVdb, buckets can be secured by setting secret_key and write_key policies. However, giving these keys out to client applications is unwise, as any user may write to any key in your bucket. Instead, you can generate access tokens, which are cryptographically signed tokens, granting access to a set of keys for a limited amount of time.

An access token is created using the KVdb API and specifying the following parameters:

• prefix: the set of keys that start with this value
• permissions: one or more permissions to grant to the token holder
• ttl: the lifetime of the token

Permissions can be one of the following and can be combined:

• read: read key values
• write: write key values
• enumerate: list keys
• delete: delete keys

To combine multiple permissions together, separate them with commas, for example: read,enumerate.

---

Creating an Access Token

Using HTTP

Make an HTTP POST request to https://kvdb.io/BUCKET/tokens/ with the following parameters:

• prefix: key prefix
• permissions: comma-separated list of permissions
• ttl: lifetime of the token in seconds

curl -d 'prefix=user:123:&permissions=read,enumerate&ttl=3600'
  -u mykey:
  https://kvdb.io/BUCKET/tokens/

Now, take the resulting access_token field from the response and use it as an access token anywhere one is accepted. You can even pass it to a bucket script to grant user-specific permissions to Lua code running in your bucket.

From a Lua Script

Make an HTTP POST request to https://kvdb.io/BUCKET/tokens/ with the following parameters:

• prefix: key prefix
• permissions: comma-separated list of permissions
• ttl: lifetime of the token in seconds

local access_token, err = kvdb.access_token({
  prefix="user:123:",
  permissions={"read", "enumerate"},
  ttl=3600})
if err then
  kvdb.say("error generating token: " .. err)
  return kvdb.exit(500)
end

kvdb.say("access token: " .. access_token)

When a bucket script is executed and an access token is provided in the Authorization header or the query string, it is automatically validated and there is no need for the Lua script to perform any additional checks.

Check out API reference guides and more code samples at the documentation portal.