Workspaces and tenancy

A workspace is one institution’s private area in SpeculaPro. Everything belongs to exactly one workspace — its users and roles, its customers and transactions, its rules, alerts, cases and reports — and nothing in one workspace can be seen from another.

In the code and the database a workspace is called a tenant. The two words mean the same thing; these docs say workspace except where they are describing the technical layer.

Why it matters

• On the SaaS service, many institutions share the same servers. The workspace boundary is what stops a PSP from ever seeing a bank’s customers — and it is enforced by the database itself, not only by the application. See Tenant isolation.
• Where the service runs in more than one region, a workspace also lives in exactly one region, and its data stays there. See Data residency and regions.
• When you self-host, you normally have just one workspace. Self-hosting is the same software with a single tenant, so nothing in these docs changes.

What a workspace holds

Setting	What it is	Example
Slug	A short, lowercase name you type when signing in. Letters, digits and hyphens; 2 to 63 characters; must start with a letter or digit. Unique across the installation.	kwekupay
Name	The institution’s display name.	Kweku Pay Ltd
Kind	The type of institution.	psp
Country	Two-letter ISO country code.	GH
Base currency	Three-letter ISO currency code that every amount is converted into. See Money and currencies.	GHS
Timezone	Where “a day” begins and ends for daily limits and calendar-day windows.	Africa/Accra
Default language	The interface language for new users.	en
Status	active, suspended or closed. On the hosted service, see A suspended workspace.	active

The kind is one of:

Kind	For
psp	Payment service providers
fintech	Fintechs that are not primarily payment providers
bank	Banks
mobile_money	Mobile money operators and electronic money issuers
microfinance	Microfinance institutions and savings and loans companies
other	Anything else

Choose the base currency and timezone carefully

Every stored amount is also converted into the base currency, and every “per day” window is calculated in the workspace timezone. Set them to match how your institution reports to its regulator.

The base currency can’t be changed once the workspace exists. The timezone can, by an administrator under Settings → Workspace, but only new calculations use it: figures already worked out stay as they were, so old and new figures may disagree. See What the time zone changes.

How to create the first workspace

Workspaces are created from the command line on the server running SpeculaPro. This is how a self-hosted installation gets its first administrator.

1. Make sure the database schema is up to date:

   speculapro migrate up

2. Create the workspace and its first administrator:

   speculapro tenant create \
     --slug kwekupay \
     --name "Kweku Pay Ltd" \
     --kind psp \
     --country GH \
     --currency GHS \
     --timezone Africa/Accra \
     --admin-email [email protected] \
     --admin-name "Abena Mensah"

   --slug, --name and --admin-email are required. The others default to psp, GH, GHS, Africa/Accra and Administrator.

3. Copy the temporary password from the output:

   workspace "kwekupay" created (0192…)
   admin: [email protected]
   temporary password (shown once, must be changed at first sign-in): …

4. Give the administrator the workspace slug, their email and the temporary password through a secure channel. At first sign-in they must choose a new password.

The temporary password is shown once

It is not stored anywhere you can read it back — only a hash of it is kept. If you lose it before the administrator signs in, the workspace has no way in. Copy it before you clear your terminal.

What creating a workspace does

In one database transaction, SpeculaPro:

1. creates the workspace;
2. creates the nine system roles — Analyst, Senior analyst, L2 investigator, MLRO, Rule author, Rule approver, Auditor, Data protection officer and Administrator (see Roles and permissions);
3. creates the administrator, gives them the Administrator role, and requires a password change at first sign-in;
4. writes a tenant.create entry to the audit log.

If any step fails, none of it is kept.

The first administrator cannot work cases

The Administrator role manages users, API keys and settings. It deliberately does not include alerts, cases or rule approval. The administrator’s first job is to invite the compliance team and give them their roles — including, if they need it, giving themselves a second role.

Signing in names the workspace

Because the same email address can exist in two workspaces, signing in asks for three things: the workspace slug, your email and your password — plus a six-digit code if you have two-factor sign-in turned on.

Teams

Inside a workspace, people can be grouped into teams, for example “AML level 1”, “Fraud desk” or “MLRO office”. A team is a named group of people who share a queue of cases. A case joins a team’s queue through an escalation policy or by hand, the Cases screen can be filtered to a team’s queue, and the team’s members are notified when a case arrives or misses its deadline.

A team is a way to organise work, not a security boundary: anyone whose role lets them work cases can still open any case in the workspace. A member can be marked as the team’s lead, which shows them first in the team; it gives no extra permissions. What a person may do always comes from their role.

Administrators create teams under Settings → Escalation. See Teams and Teams and team queues.

Related

• Roles and permissions
• Tenant isolation
• Self-hosting
• Data residency and regions