API Reference/Companies

Companies

Manage your tenant's organizational data, administrators, and API keys. These endpoints are designed for management dashboards rather than standard transaction flows.

Tenant Info

GET

/v1/core/companies/me

Returns the currently authenticated company profile based on the x-company-id header.

Auth

curl -X GET "https://api.switchlock.co.zw/v1/core/companies/me" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

{
  "id": "cmp_01HXYZ...",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "system_fee_basis_points": 150,
  "created_at": "2026-06-20T10:00:00.000Z"
}

Administrators

Manage the personnel who have dashboard access to your tenant.

GET

/v1/core/companies/admins

List all administrators for the company.

Auth

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

Response Example

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

POST

/v1/core/companies/admins

Add a new administrator to your company.

Auth

Field	Type	Required	Description
firstName	string	Yes	First name.
lastName	string	Yes	Last name.
email	string	Yes	Valid email address.
role	enum	Yes	Role enum: admin or manager.
password	string	No	Defaults to Welcome123! if omitted.

curl -X POST "https://api.switchlock.co.zw/v1/core/companies/admins" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "role": "string",
  "password": "string"
}'

POST

/v1/core/companies/admins/:id/remove

Remove an administrator from the company. The OWNER role cannot be removed.

Auth

Field	Type	Required	Description
id	string (path)	Yes	UUID of the administrator.

curl -X POST "https://api.switchlock.co.zw/v1/core/companies/admins/value/remove" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string"
}'

API Keys

For security, the raw zl_sk_... key is never returned by the list endpoint. Only the prefix and status are available.

GET

/v1/core/companies/api-keys

Returns metadata for all API keys associated with the company.

Auth

curl -X GET "https://api.switchlock.co.zw/v1/core/companies/api-keys" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

[
  {
    "id": "key_01HXYZ...",
    "name": "Production Server",
    "key_prefix": "a1b2c3d4",
    "is_active": true,
    "created_at": "2026-06-23T09:01:00.000Z"
  }
]

POST

/v1/core/companies/api-keys/roll

Rolls a new API key. The raw secret key is only returned once in the response. Store it safely immediately.

Auth

Field	Type	Required	Description
name	string	Yes	Display name for the new API key.

curl -X POST "https://api.switchlock.co.zw/v1/core/companies/api-keys/roll" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'

Response Example

{
  "id": "key_01HXYZ...",
  "key_prefix": "a1b2c3d4",
  "secret_key": "zl_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "message": "Key generated. This secret will never be shown again."
}

Next steps

Getting Started

Review the quickstart guide.

Postman Collection

Download the collection to test these endpoints.