diff --git a/docs/email-reports.md b/docs/email-reports.md index a821439f..d2259944 100644 --- a/docs/email-reports.md +++ b/docs/email-reports.md @@ -18,4 +18,4 @@ All the stats are embedded directly into the email and there's no need to go to Email reports can be set to be sent to multiple recipients. Enable the weekly and/or monthly report, add an individual recipient into the **Report recipients** field and click on the **Add recipient** button. -You can set the email reports to be sent to as many people as you want. You can remove individual report recipients or completely stop the scheduled email reports at any time. +You can set the email reports to be sent to as many people as you want. Email report recipients do not count toward your [team member limit](users-roles.md#how-the-team-member-limit-is-counted). You can remove individual report recipients or completely stop the scheduled email reports at any time. diff --git a/docs/shared-links.md b/docs/shared-links.md index 158a4b11..f2a41696 100644 --- a/docs/shared-links.md +++ b/docs/shared-links.md @@ -10,6 +10,8 @@ Shared links are useful for specific use cases such as if you want to share your People that you send your shared link to can view the stats dashboard without having a Plausible Analytics account and without needing to log in. They can only view the specific dashboard that you shared and can't see any other sites that you have added to your Plausible account. +People who view a shared link do not count toward your [team member limit](users-roles.md#how-the-team-member-limit-is-counted). + :::tip Want to share the stats with your team members instead? See how to [invite team members and set user roles](users-roles.md) ::: diff --git a/docs/sites-api.md b/docs/sites-api.md index 26135106..85935ff9 100644 --- a/docs/sites-api.md +++ b/docs/sites-api.md @@ -32,12 +32,14 @@ Each request must be authenticated with an API key using the Bearer Token method ## Authentication -To create a new sites API key, log in to your Plausible Analytics account. In the top-right menu, click on your account name and go to settings. +When you create a Sites API key, it is scoped to the team selected in the top-right menu. It can manage only the sites owned by that team. It does not include sites owned by other teams or sites where the key owner is only a Guest Viewer or Guest Editor. -Next, go to the **API Keys** section in the left-hand sidebar. Click the **New API Key** button, choose **Sites API** and save the key as it will only be shown once. After saving the key, click on **Create API Key** to confirm its creation. +To create a new Sites API key, log in to your Plausible account and select the team whose sites you want to manage. Click your account name, open the settings and go to **API Keys**. Click **New API Key**, choose **Sites API** and save the key because it will only be shown once. Click **Create API Key** to confirm its creation. After creating an API key, you can authenticate your request by sending the key in the Authorization header of your request. +The [API key role restrictions](stats-api.md#who-can-create-a-stats-api-key) are the same for Stats API and Sites API keys. If the key owner leaves or is removed from the team, the key can no longer access that team's sites. + ## Endpoints ### GET /api/v1/sites @@ -54,15 +56,15 @@ curl -X GET https://plausible.io/api/v1/sites \ "sites": [ { "domain": "test-domain1.com", - "timezone": "Europe/London", + "timezone": "Europe/London" }, { "domain": "test-domain2.com", - "timezone": "Europe/London", + "timezone": "Europe/London" }, { "domain": "test-domain3.com", - "timezone": "Europe/London", + "timezone": "Europe/London" } ], "meta": { @@ -113,17 +115,17 @@ curl -X GET https://plausible.io/api/v1/sites/teams \ { "id": "4d3dae3b-2a44-4aaa-baac-6bb55234a435", "name": "My Personal Sites", - "api_available": false, + "api_available": false }, { "id": "ef828bca-8a1b-49f6-b829-dee1c9f7d628", "name": "Some Team", - "api_available": true, + "api_available": true }, { "id": "59e4d5b3-fc1c-464d-95f2-dbe6983396be", "name": "Another Team", - "api_available": true, + "api_available": true } ], "meta": { diff --git a/docs/stats-api-v1.md b/docs/stats-api-v1.md index 70c3bcfb..3ff9b2b1 100644 --- a/docs/stats-api-v1.md +++ b/docs/stats-api-v1.md @@ -14,8 +14,7 @@ The Plausible Stats API offers a way to retrieve your stats programmatically. It The API accepts GET requests with query parameters and returns standard HTTP responses along with a JSON-encoded body. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. -Each request must be authenticated with an API key using the Bearer Token method. You can obtain an API key for your account by going to your user -settings page [plausible.io/settings](https://plausible.io/settings). +Each request must be authenticated with an API key using the Bearer Token method. API keys are scoped to the team selected when they are created. See [Stats API authentication](stats-api.md#authentication) for setup instructions, role restrictions and site access rules. API keys have a rate limit of 600 requests per hour by default. If you have special needs for more requests, please contact us to request more capacity. diff --git a/docs/stats-api.md b/docs/stats-api.md index 719a57a4..a8e8d623 100644 --- a/docs/stats-api.md +++ b/docs/stats-api.md @@ -12,7 +12,7 @@ import CodeBlock from '@theme/CodeBlock'; import { SiteContextProvider } from '../src/js/sites.tsx'; import PlanFeatureNote from '@site/src/components/PlanFeatureNote'; -Plausible Stats API is a powerful single endpoint HTTP interface to **view historical and real-time stats**. In a nutshell, the endpoint `/api/v2/query` accepts both simple and complex stats queries in the POST request body and returns the metrics as JSON. +Plausible Stats API is a read-only HTTP interface for **viewing historical and real-time stats**. The `/api/v2/query` endpoint accepts simple and complex stats queries in the POST request body and returns the metrics as JSON. :::tip[Not what you need?] Take a look at our [Events API Reference](events-api.md) if you want to record pageviews or custom events for your sites, or [Sites API Reference](sites-api.md) if you want to manage your sites over the API. @@ -22,12 +22,34 @@ Take a look at our [Events API Reference](events-api.md) if you want to record p ## Authentication -To create a new stats API key, log in to your Plausible Analytics account. In the top-right menu, click on your account name and go to settings. +API keys are scoped to one team. The team selected in the top-right menu when you create the key determines which sites it can query. A key does not inherit access to every site its owner can view across Plausible. -Next, go to the **API Keys** section in the left-hand sidebar. Click the **New API Key** button, choose **Stats API** and save the key as it will only be shown once. After saving the key, click on **Create API Key** to confirm its creation. +To create a Stats API key: + +1. Log in to your Plausible account and select the team whose sites you want to query. +2. Click your account name, open the settings and go to **API Keys**. +3. Click **New API Key**, choose **Stats API** and save the key because it will only be shown once. +4. Click **Create API Key** to confirm its creation. After creating an API key, you can authenticate your request by sending the key in the Authorization header of your request. +### Who can create a Stats API key? + +| Role in the selected team | Can create a key for that team? | +| --- | --- | +| Owner, Admin, Editor or Billing | Yes | +| Viewer | No | +| Guest Viewer or Guest Editor for an individual site | No | + +### Which sites can a key access? + +A Stats API key can query sites owned by the team it was created for. It cannot query: + +- Sites owned by another team +- Sites where the key owner is only a Guest Viewer or Guest Editor + +For example, suppose you are a Guest Viewer for a client's site. A Stats API key that you create under **My personal sites** cannot query that client's site. The client team would need to create a key scoped to their team. + ### Example curl request In the following request, replace `YOUR-KEY` with a reference to your stats API key and `site_id` value with your domain as you've added it to your Plausible account. diff --git a/docs/subscription-plans.md b/docs/subscription-plans.md index 8b198d62..4eb726b4 100644 --- a/docs/subscription-plans.md +++ b/docs/subscription-plans.md @@ -57,6 +57,8 @@ Your subscription tier is based on the total number of **pageviews** and **[cust Custom events include outbound link clicks, file downloads, form submissions, 404 error tracking and any manually tracked events. Adding a [pageview goal](pageview-goals.md) does not count towards your usage. +Team member limits are calculated separately from traffic. Full team members, site guests and pending invitations count toward the limit. Email report recipients and people who view shared links do not. See [how the team member limit is counted](users-roles.md#how-the-team-member-limit-is-counted) for the full rules. + Check your current usage in the **Subscription** section of your account settings and pick a tier that matches.
diff --git a/docs/team-settings.md b/docs/team-settings.md index e2193d47..ce834575 100644 --- a/docs/team-settings.md +++ b/docs/team-settings.md @@ -25,9 +25,10 @@ See [users and roles](users-roles.md) for full details on inviting people and ma See the [billing section](trial-to-paid.md) for details on plans, invoices and payment. **API keys** -- Create and manage API keys for the Stats API and Sites API +- Create and manage your API keys for the Stats API and Sites API +- Each key is scoped to the team selected in the top-right menu when it is created -See the [Stats API](stats-api.md) and [Sites API](sites-api.md) docs for how to use them. +See [Stats API authentication](stats-api.md#authentication) for role restrictions and site access rules, or the [Sites API](sites-api.md) docs for how to use a Sites API key. **Single Sign-On (SSO)** - Configure SSO for your team via Google Workspaces, Microsoft Entra or Okta diff --git a/docs/users-roles.md b/docs/users-roles.md index f6f1d62a..175948e7 100644 --- a/docs/users-roles.md +++ b/docs/users-roles.md @@ -51,11 +51,11 @@ If you then add more sites to your account, they appear in "My personal sites" a When managing team members, you can choose between five different roles: -1. **Owner** gets access to everything and can manage the team, sites, API keys, 2FA enforcement, SSO and the subscription itself. An owner can also delete a team -2. **Admin** can manage team members, sites and API keys -3. **Editor** gets access to all your stats dashboards and can change the site settings -4. **Billing** can manage your Plausible subscription, payments and invoices -5. **Viewer** can view the stats dashboards of the sites that the team owns +1. **Owner** can manage the team, sites, their own API keys, 2FA enforcement, SSO and the subscription. An owner can also delete the team +2. **Admin** can manage team members, sites and their own API keys +3. **Editor** can view all stats dashboards, change site settings and manage their own API keys +4. **Billing** can manage the subscription, payments, invoices and their own API keys +5. **Viewer** can view the stats dashboards of sites that the team owns but cannot create API keys You can change the role of a team member at any time: @@ -68,6 +68,12 @@ That's it. The team member now has a different role. Note that you need to be an owner or an admin of a team to change team member roles. +### API key access by role + +Owner, Admin, Editor and Billing team members can create their own API keys for the selected team. Viewer team members cannot create API keys. Guest Viewers and Guest Editors cannot create keys for a team where they only have access to individual sites. + +API keys are scoped to the team selected when they are created. They do not automatically include sites in other teams or sites where the key owner is only a guest. See [Stats API authentication](stats-api.md#authentication) for examples and the full access rules. +
Change roles, delete team member
@@ -168,3 +174,22 @@ You can remove a guest from having access to a site at any time: That's it. The guest has now been removed from the specific site. Note that you need to be an owner or an admin of the team that owns the site to remove a guest. + +## How the team member limit is counted + +The team member limit includes both full team members and guests who can log in to individual sites. It is based on unique email addresses, not the number of roles or sites. + +The following count toward the limit: + +- Team members +- Guest Viewers and Guest Editors +- Pending invitations to join the team or an individual site + +The same person counts once even if they are a member of the team and a guest on multiple sites. + +The following do not count toward the limit: + +- Email report recipients +- People who view a shared link or an embedded dashboard based on a shared link + +Email report recipients and shared-link viewers do not get team or site login access. If they are also invited as a team member or site guest, they count from the invitation. See [pricing and subscription plans](subscription-plans.md) for the limits included with each plan.