Companies

Administrator Management

Administrators are human logins for your company — distinct from API keys, which authenticate your server. Each admin signs in with email and password, receives a JWT, and operates through the dashboard or API.

Administrators vs API keys

Both grant access to your company's data, but they are different credentials for different actors. Never use a JWT in server-to-server code, and never use an API key to log into the dashboard.

	Administrator	API Key
Who it authenticates	A named human with a role	Your server process
Credential format	Email + password → JWT	zl_sk_… (bearer token)
Header used	Authorization: Bearer <jwt>	x-api-key: zl_sk_…
Lifetime	Short-lived JWT (1h) + refresh	Long-lived until revoked
Can generate API keys	Yes	No
Can initiate manual operations	Yes	Yes
Tied to a person	Yes — remove when they leave	No — scoped to a service

Roles

Every admin has a role that determines what they can see and do. The first admin created at company registration is always OWNER — this role cannot be removed via the API.

OWNER

Full control. Created at registration. Can manage all other admins, generate and revoke API keys, update company settings, approve or reject transactions, and view all data.

admin

Company-wide administrative access. Can manage API keys, view and operate on transactions, manage other non-owner admins, and update company settings.

manager

Operational access. Can view transactions, trigger manual operations, and manage users — but cannot manage API keys or other administrators.

The role field on POST /v1/core/companies/admins is a free string. The values OWNER, admin, and manager are the platform conventions — your application can use additional role strings and enforce their meaning in your own logic.

Admin login flow

Admins authenticate with their email and password. The API returns a short-lived access token and a refresh token. Use the access token as a Bearer credential for admin-scoped operations.

curl -X POST "https://api.switchlock.co.zw/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@acme.co.zw",
    "password": "SuperSecret123!"
  }'

Response — 200 OK

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

Access tokens expire after 1 hour. Use the refreshToken to obtain a new one without re-entering credentials. See the Authentication docs for the refresh flow.

Add an administrator

Only an authenticated admin (JWT Bearer) can add other admins. The new admin's password is bcrypt-hashed (10 rounds) before storage — it defaults to Welcome123! if omitted. Require the new admin to change their password on first login.

curl -X POST "https://api.switchlock.co.zw/v1/core/companies/admins" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Rudo",
    "lastName": "Chikwanda",
    "email": "rudo@acme.co.zw",
    "role": "manager",
    "password": "Temp@2026!"
  }'

Response — 201 Created

{
  "id": "adm_01HXYZ...",
  "firstName": "Rudo",
  "lastName": "Chikwanda",
  "email": "rudo@acme.co.zw",
  "role": "manager",
  "company_id": "cmp_01HXYZ...",
  "created_at": "2026-06-23T09:05:00.000Z"
}

Field	Required	Description
firstName	Yes	Admin's first name
lastName	Yes	Admin's last name
email	Yes	Login email — must be unique within your company
role	Yes	Role string, e.g. admin or manager
password	No	If omitted, defaults to Welcome123! — change on first login

List administrators

Returns all admin accounts for your company, ordered newest first. Password hashes are never returned.

curl "https://api.switchlock.co.zw/v1/core/companies/admins" \
  -H "x-api-key: zl_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "x-company-id: cmp_01HXYZ..."

Response — 200 OK

[
  {
    "id": "adm_01HXYZ...",
    "firstName": "Jackson",
    "lastName": "Doe",
    "email": "admin@acme.co.zw",
    "role": "OWNER",
    "created_at": "2026-06-23T09:00:00.000Z"
  },
  {
    "id": "adm_01HABC...",
    "firstName": "Rudo",
    "lastName": "Chikwanda",
    "email": "rudo@acme.co.zw",
    "role": "manager",
    "created_at": "2026-06-23T09:05:00.000Z"
  }
]

Remove an administrator

Removing an admin is a hard delete — the record is permanently removed. The admin loses all access immediately; their JWT will fail on the next request. Revoke any API keys they generated before removing them.

curl -X POST "https://api.switchlock.co.zw/v1/core/companies/admins/adm_01HABC.../remove" \
  -H "x-api-key: zl_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "x-company-id: cmp_01HXYZ..."

Response — 200 OK

{ "success": true }

Removal is scoped to your company — you cannot remove an admin from another company's tenant. The OWNER admin created at registration cannot be removed via this endpoint.

Security guidance

Admins can generate and revoke API keys

Any admin can create new API keys for your company. This means a compromised admin account is equivalent to a compromised server key. Protect admin credentials with the same care.

Offboarding checklist

When an admin leaves: (1) revoke any API keys they created, (2) remove their admin account. Do both — removal alone does not invalidate keys they already generated.

Default password must be changed

If you add an admin without a password, they receive Welcome123!. This is known — require them to change it before they perform any sensitive operation.

Principle of least privilege

Assign the manager role to people who need to view and operate transactions but not manage keys or other admins. Reserve admin and OWNER for those who genuinely need that access.

Admin accounts can view transactions

All admin roles have read access to your company's transaction history, escrow states, and user data. Treat admin access as equivalent to read access to your entire ledger.

Quick reference

Action	Method	Path	Auth
Add admin	POST	/v1/core/companies/admins	JWT Bearer
List admins	GET	/v1/core/companies/admins	x-api-key + x-company-id
Remove admin	POST	/v1/core/companies/admins/:id/remove	x-api-key + x-company-id
Admin login	POST	/v1/auth/login	Public

Next steps

Authentication

JWT refresh flows, error codes, and how x-api-key and Bearer tokens interact.

API Key Management

Generate, list, and revoke server keys — the credential type your server code uses.

How Tenants Work

Multi-tenant isolation, company IDs, slugs, and the MERCHANT vs DEVELOPER business model.

Getting Started

Full end-to-end walkthrough from registration through funding your first escrow.