Permissions and data scope

A token acts as you. It reaches the surveys you can open on the Potloc platform and does on them what your role there lets you do — nothing is granted by connecting, and nothing is taken away.

How access is decided

Access is per survey, not per account. Potloc records a role for you on each survey you have been given, and that row is the only thing that grants access: a survey you hold no role on does not appear in list_surveys. Naming its id in get_survey, list_data_layouts or list_responses returns a not-authorized error, as does naming one of its questionnaires in get_questionnaire; list_questions, list_reports and list_questionnaire_comments instead come back as an empty page with total_count: 0, so an empty result there is a permission answer rather than a bug.

There is no override. A Potloc employee who connects here is authorized exactly as you are: no role on a survey, no access to it.

One tool sits outside all of this. get_current_user returns the account the connection is authenticated as and needs no role on anything, since it tells your assistant only who it is already connected as. The id it returns is the one created_by.id carries on a report, so comparing the two is how your assistant knows which reports are its own to move in or out of private.

What each role unlocks

Role on the survey	Read surveys, questions, reports, charts	Read a questionnaire and its comments	Comment on a questionnaire	Author questionnaires	Share a report by link	Rename and reorder reports	Read raw responses
None	—	—	—	—	—	—	—
Viewer	✓	✓	—	—	—	—	—
Contributor	✓	✓	✓	—	✓	—	—
Creator	✓	✓	✓	✓	✓	✓	✓

These are the roles the sharing panel on the platform assigns. A few accounts carry an elevated role above Creator; it reaches everything Creator does.

Four rules narrow this further:

• Potloc-crafted questionnaires are read-only. When Potloc’s research team writes a questionnaire as part of your engagement, the authoring tools refuse it so the methodology stays intact, whatever your role. You can still read it — but only once it reaches review or completed status. Questionnaires you built yourself are yours to edit until they reach review; from then on they are read-only as well. Potloc’s research team can also take one over at your request, and it counts as Potloc-crafted from then on. The potloc_crafted field on every questionnaire tells the two apart.
• Comments run on any questionnaire you can read, Potloc-crafted ones included — that channel is how you ask the research team to revisit one. A comment stands once you leave it: change your mind and leave another, or edit it on the platform.
• Who can view a report is one setting. A report’s visibility is private (only its author), project (everyone with a role on the survey) or public (also anyone holding its link, without signing in, with or without a password). Only a report’s author can move it in or out of private, even as a Creator. A Contributor or a Creator can turn the public link on or off, the same as on the platform.
• Raw responses need Creator, and a released survey. list_data_layouts and list_responses both need Creator on the survey. list_responses also returns data only once the survey’s raw data is released for export; until then it answers that the survey is not released. list_data_layouts has no such gate and lists the published layouts either way.

The data boundary

Questionnaire responses only. The server returns the answers to your survey and the analysis built on them. list_responses is the only tool that returns respondent-level rows, and it renders one of the data layouts Potloc has published on your survey rather than choosing columns itself: it gives you the same columns as the spreadsheet that layout exports, no more. The default layout leads with a Potloc reference uuid per respondent.

The rest of Potloc’s platform is not on this server at all — no pricing, no deals, no sampling or fieldwork operations, no panel supply, and no link into an internal Potloc surface. Every url a tool returns points at a page you can open yourself.

The tool reference lists every field, tool by tool.

When access is refused

A refusal comes back as a tool error your assistant can read and recover from, not as a connection failure:

Not authorized to show? this Survey

Reports and charts go further: a report you may not read and a report that does not exist get the same “not found” answer, so a refusal never confirms that someone else’s report is real.