Organisations & Projects

permio.organisation.v1.OrganisationService manages organisations, projects, API keys and team members. The dashboard is built on it, and it’s the easiest way to do all of this.

Mostly for the dashboard

These calls check organisation-level permissions such as project.create or apiKeys.list. Dashboard users get these through their role in the organisation. An API key’s project grants don’t include them, so most calls on this page return PERMISSION_DENIED for an API key.

API host

The API is at https://api.perms.io. The examples on this site read the host from a PERMIO_API shell variable:

export PERMIO_API=https://api.perms.io
export PERMIO_API_KEY=perms_...   # your API key

Organisations

RPC	REST	Notes
CreateOrganisation	POST /organisation-service/v1/organisation	Body: name, user_id. Also creates the default project.
GetOrganisation	GET /organisation-service/v1/organisation/{id}	Returns organisation.
UpdateOrganisation	PUT /organisation-service/v1/organisation/{id}	Body: name. Needs organisation.update.
GetUsersOrganisation	GET /organisation-service/v1/organisation/user	Query: user_id. Returns the user’s organisation.
GetOrganisationDashboard	GET /organisation-service/v1/organisation/{organisation_id}/dashboard	total_roles, total_permissions, total_principals, total_users. Needs organisation.dashboard.view.

Organisation

Field	Type	Description
id	string	Organisation ID.
name	string	Display name.
users	User[]	Members (id, email).
created_at, updated_at	Timestamp
billing_customer	BillingCustomer	Billing contact (id, organisation_id, name, email).

Projects

Every organisation has a default project, which can’t be deleted. Project names are 1–32 characters: lowercase letters, digits and -.

RPC	REST	Notes
CreateProject	POST /organisation-service/v1/organisation/{organisation_id}/project	Body: name. Needs project.create.
GetProject	GET /organisation-service/v1/organisation/{organisation_id}/project	Query: project_name. Needs project.get.
GetProjectsForOrganisation	GET /organisation-service/v1/organisation/{organisation_id}/projects	Query: pagination.limit, pagination.cursor, search. Returns projects and pagination.
DeleteProject	DELETE /organisation-service/v1/organisation/{organisation_id}/project	Query: project_name. Needs project.delete. Invalidates the project’s API keys.

Project: organisation_id, name, created_at.

API keys

See API keys for the key format and access levels.

RPC	REST	Notes
CreateAPIKey	POST /organisation-service/v1/organisation/{organisation_id}/api-key	Body: project_name, name, access (API_KEY_ACCESS_CHECK or API_KEY_ACCESS_FULL; left out means check). Returns api_key, whose key is the only time the secret is returned. Needs apiKey.create on the project, and every permission of the chosen access level.
ListAPIKeys	GET /organisation-service/v1/organisation/{organisation_id}/api-key	Query: project_name, pagination.*, search. Returns api_keys and pagination. Needs apiKeys.list.
InvalidateAPIKey	DELETE /organisation-service/v1/organisation/{organisation_id}/api-key/{id}	Query: project_name. The key stops working immediately.

APIKey

Field	Type	Description
id	string	Key ID. This is also the key’s principal ID.
name	string	Display name.
key	string	The secret, set only in the CreateAPIKey response.
created_at	Timestamp
invalidated	bool	true once invalidated.
access	APIKeyAccess	API_KEY_ACCESS_CHECK or API_KEY_ACCESS_FULL (API_KEY_ACCESS_UNSPECIFIED is treated as check).

Note

CreateAPIKey with access: API_KEY_ACCESS_FULL is refused with PERMISSION_DENIED unless the caller holds every permission that level grants on the project. Choosing the level in the dashboard is being added; until then, keys created there get check access.

Team members

RPC	REST	Notes
InviteUserToOrganisation	POST /organisation-service/v1/organisation/{organisation_id}/invite	Body: email.
RemoveUserFromOrganisation	POST /organisation-service/v1/organisation/{organisation_id}/user/{user_id}	Needs organisation.user.remove.
SetUsersOrganisation	POST /organisation-service/v1/organisation/{id}/user	Body: user_id, email. Needs user.organisation.set.

Usage

RPC	REST	Notes
GetPrincipalUsageStats	GET /organisation-service/v1/organisation/{organisation_id}/principal-usage	Current principal count against your plan. Needs billing.view.
GetUsageHistory	GET /organisation-service/v1/organisation/{organisation_id}/usage-history	Query: days (default 30). Returns history (date, count). Needs billing.view.

Example

With the TypeScript SDK, these RPCs are on permio.organisations:

import { paginate } from "permio";

for await (const project of paginate(
  (pagination, signal) =>
    permio.organisations.getProjectsForOrganisation({ organisationId: "your-org-id", pagination }, { signal }),
  (res) => res.projects,
)) {
  console.log(project.name);
}