Orgs, people and roles · Pinecall Docs

An org is your company on Pinecall: its agents, its numbers, its calls and its people. Each person has a role that says what they may do, and a switch that says whether they may do it in production. Servers run on tokens of their own, which belong to the org and not to a person.

How it works#

PeopleInvited by email, each with a role. One person may belong to several orgs. The production switchWhether a person may act in production. An admin's is always on. Your keyOne per person, per device, made when you sign in. It opens the sandbox and production. Server tokensThe org's, for a process that runs an agent. The sandbox's or production's.

People and roles#

An admin invites people from the console's Team screen, on production's console. Each invitation names an email, a role and the production switch. The person gets a one-use link, chooses a password, and is in. Team is also where a role is changed, the switch is moved, a password is reset, and a person is disabled or removed.

A role is a preset of what that person's keys open:

role	may	for
`qa`	read finished calls and the test suites	reviewing quality
`supervisor`	+ listen to live calls, whisper, take a call over, the agent's words and what it remembers	the people on the phone floor
`manager`	+ numbers, tokens, provider keys, usage and the team	running the floor and the org's accounts, never which model an agent runs on
`developer`	run agents, their calls, the pipeline, words, knowledge, memory and tests	writing and running the agent
`admin`	everything	the org's owner

Each role is a fixed set of scopes, and every route of the API asks for one scope. Which screens each scope opens is in The console.

role	scopes
`qa`	`calls`, `evals`
`supervisor`	`calls`, `evals`, `supervise`, `talk`, `memory`, `words`
`manager`	`calls`, `evals`, `supervise`, `talk`, `memory`, `numbers`, `keys`, `providers`, `usage`, `team`, `words`
`developer`	`app`, `calls`, `talk`, `supervise`, `pipeline`, `knowledge`, `memory`, `evals`, `words`
`admin`	every scope

You can only hand out what you hold. A manager invites qa, supervisors and managers, never a developer or an admin. Nobody changes their own role or their own switch: another admin does. An org's last active admin cannot be removed.

An org can also sign its people in with its own identity provider (Google Workspace, Okta, Entra or any OpenID Connect provider). An admin sets it up on the Team screen.

The production switch#

The role says what a person does; the switch says whether they may do it in production. It is read on every request, so turning it off closes the very next --prod. Without it, a person still has the whole sandbox (Sandbox and production).

Your key#

You never type a password into a terminal. In a project's folder:

Terminal

~/clinica-norte $ pinecall link
open this to sign in:
https://cloud.pinecall.io/cli?c=cli_…

waiting…
signed in to https://cloud.pinecall.io as Ana García
▸ clinica · PINECALL_KEY written to .env

You sign in in the browser, and the terminal gets a key of its own, labelled with this machine. pinecall link writes it to the project's .env as PINECALL_KEY. That one key opens the sandbox, and production with --prod while your switch is on. A project of another org is another folder, linked on its own.

.env holds your key. pinecall link warns you until .gitignore names .env: a key committed is a key published.

pinecall whoami says which org and which key a folder is using, and where the key came from. Run it first when a command is refused and you do not know why.

Terminal

$ pinecall whoami
gateway https://cloud.pinecall.io · key from .env · sandbox
  org clinica · key k_4f2a1d9c66b30e17 · sandbox · ana-macbook · production: yes
  a person's key: the sandbox without --prod, production with it

Server tokens#

A server that runs an agent has no browser and no person. It runs on a server token, made in the console under Settings ▸ Tokens and shown once, as PINECALL_KEY=pc_live_… (production) or PINECALL_KEY=pc_test_… (sandbox). Run it on your own server walks through making one and where to keep it.

A server token opens what running an agent needs: app, calls, talk, knowledge and evals, that is holding the agent, its calls, talking to it, pushing its knowledge and running its tests. It never opens the org's people, numbers or money. It opens the sandbox only, or production only. Only a person with production access can make a production token.

A server token belongs to the org. When the person who made it is removed, every key of theirs is revoked, and the token keeps working. Tokens are revoked one by one from the same screen.

Where your org's plan caps seats, an invitation takes a seat as soon as it is sent. Disabling a person frees it.

Next steps#

Sandbox and productionWhat the sandbox and production each hold. Limits & provider keysWhat the org may use, and running on your own vendor keys. Run it on your own serverWhere a server token goes. pinecall linkEvery flag of link, login and whoami.