Permissions

Permissions decide who can see and do what on your platform, and how much of it. They cover your collections, forms and pages, and they hold the usage your plans include, such as 5 guides on one plan and 20 on another.

Anything no permission mentions is invisible to everyone except admins. A new collection, form or page stays hidden until you give someone access to it. Admins always see and do everything.

If your platform has no sign-in set up, nobody can be told apart, so everything is open to everyone.

The Permissions Page

Open Permissions in the project menu. Each permission is a card, with a line saying who it's for and what it covers. Click Add to create one, give it a name, and its page opens.

A permission's page is built from sections. Who is always there. Add the others with Add a section:

Access: what they can see and do.
Usage: how many they get.
Over time: resets, rate limits and dates. Needs Usage.
At the limit: what happens when they run out. Needs Usage.
When the plan changes: what happens when a plan ends or changes.

Remove a section with its trash button. Save applies everything at once, and Discard throws your changes away.

Each collection, form and page shows who can use it, with a link to the permissions that mention it.

Who

Pick one audience:

Signed-in customers
Anyone, including people who aren't signed in. Use this for public pages and forms such as a contact form.
Admins only

Signed-in customers can be narrowed down. Everything you narrow by has to match:

Plans: only customers on these plans. Leave empty for every signed-in customer.
Plan statuses: which states of those plans count. Active, cancelling but still paid up, in a trial, and past due all count unless you pick some.
Account roles: owner or member. Each account has one person until teams exist, and that person is its owner.
People: email addresses, one per line.

When several permissions apply to the same customer, any one of them allowing something is enough.

Access

Each access line covers collections, forms or pages:

Collections: view, create, edit and delete. Which records chooses all records, only the records the customer created, or the records of their account.
Forms: submit, and view the submissions.
Pages: view. A page only shows in the menu for people who can view it.

Add as many lines as you need with Add access.

Usage

Usage counts one of two things:

Records in collections. Records in every collection you pick count toward one shared number, so Tours and Exhibits together can make up 5 guides.
Uses reported by your own code, such as API calls, sessions or exports. Your code reports each use with the call shown on the page (see Reporting usage from your own code).

Then set how many. When the permission names plans, each plan gets its own number. Leave a number empty for no limit. 0 means none.

Counted per chooses whose number it is: each person, each account, or the whole platform together, for example 100 beta spots in total.

For records, Counting chooses between what the customer has right now, where deleting a record frees a slot, and everything they've ever created.

When several usages count the same collection, a record can only be created if every one of them has room.

Over Time

Reset: never, every day, week, month or year, with each customer's billing period, every period from a date you choose, or over the last few days on a rolling basis. A usage that resets counts everything used, so deleting doesn't give anything back.
Carry unused allowance into the next period: what wasn't used in the last period is added to this one.
Rate limit: no more than a number per minute or per hour, whatever is left in the allowance.
Available: the allowance only exists between two dates, or for a number of days after the customer signs up or their plan starts. Outside that window it's 0.

At the Limit

Refuse: the customer is told they've reached their limit.
Allow it and flag them as over: it goes through, and the customer sees they're over.
Allow it and bill the extra: it goes through, and each extra one is added to the customer's next invoice at the price you set.

Warn them at shows the customer a warning once they've used that percentage of their allowance.

Top-ups are packs customers can buy to get more, such as 100 more calls for $5. They pay through Stripe Checkout. With a reset, a top-up lasts until the next one. Without a reset, it lasts.

When the Plan Changes

When their plan ends, customers keep nothing or read-only access. Grace days keeps everything working for that many days after the plan ends. Their records are never deleted.
Start counting again when they change plans restarts the count from the new plan's start.

Changing plans keeps what the customer already has. Someone with 10 guides who moves to a plan allowing 5 keeps their 10 and can't create more until they're under 5.

What Customers See

The generated platform hides what a customer can't use: pages leave the menu, and buttons to create, edit or delete disappear. Anything refused is explained, such as reaching a limit. Signed-in customers see their usage on the home page, with any warning and the top-ups they can buy.

Reporting Usage From Your Own Code

For a usage that counts uses reported by your own code, your platform has these endpoints. The usage's id is shown on its permission page.

POST /api/usage/{id}/consume with a signed-in customer's token uses one, or { "amount": 3 }. It checks and uses in one step, so two calls at the same moment can't both take the last one. Send an idempotencyKey and a retry with the same key isn't counted twice. When nothing is left, it's refused with USAGE_LIMIT_REACHED, or RATE_LIMITED past the rate limit.
POST /api/usage/{id}/release, /grant and /reset give back, add or reset a customer's usage: { "userId": "...", "amount": 1 }. Only your own server can call these, with the X-Usage-Key header set to the USAGE_API_KEY you give your platform.
GET /api/usage lists the signed-in customer's usage, and GET /api/usage/{id}/history the last uses.

See the API reference for the details.

Permissions From the CLI

devour sync writes your permissions into the configuration file, and devour setup --config <file> applies them. Collections, forms, pages and plans are named, not identified:

"permissions": [
  {
    "name": "Guides",
    "who": { "plans": ["Starter", "Pro"] },
    "access": [
      { "collections": ["Tours", "Exhibits"], "actions": ["view", "create", "edit", "delete"], "records": "account" },
      { "pages": ["Guide builder"], "actions": ["view"] }
    ],
    "usage": {
      "counts": { "collections": ["Tours", "Exhibits"] },
      "max": { "Starter": 1, "Pro": 10 },
      "per": "account",
      "kind": "total"
    }
  },
  {
    "name": "Contact form",
    "who": { "audience": "anyone" },
    "access": [{ "forms": ["Contact"], "actions": ["submit"] }]
  }
]

A permission missing from the file is removed after setup asks, or right away with --yes. Every key is listed in the CLI reference.

Projects Made Before Permissions

Existing projects were moved over without changing what their customers can do:

A Signed-in customers permission covers every collection, form and page. Collections that were private keep each customer to their own records.
Each usage limit became a permission named after it, for the plans of the project, counting the same collections. A plan that had no number for a limit got 0, which is what it allowed before.