Tenants API: Create, Update, and Manage School Tenants

In Cole, a tenant represents a single school (or other educational institution). The multi-tenant architecture means every piece of data — academic periods, professors, students, courses — belongs to exactly one tenant. Two distinct role categories govern tenant management: super-admin has platform-wide visibility and can create or delete any tenant, while director has access only to the tenant they were assigned to when their account was created. When a super-admin creates a tenant, Cole simultaneously creates a director user account for that school and attaches every available module to the tenant in an inactive state, ready to be individually enabled later.

Tenant CRUD (super-admin)

POST /api/tenants

Creates a new tenant, provisions a director user for it, and attaches all existing modules in an inactive state — all within a single database transaction. Authentication required: Authorization: Bearer <token> — role super-admin

Request body

name

string

required

The official name of the school. Example: "Colegio Lincoln".

slug

string

required

A URL-safe unique identifier for the tenant. Must be unique across all tenants. Example: "lincoln".

director_name

string

required

Full name of the director user that will be created for this tenant.

director_email

string

required

Email address for the director account. Must be unique in the users table.

password

string

required

Initial password for the director account. Stored as a bcrypt hash.

Response `200 OK`

tenant

object

The newly created tenant record.

Show tenant fields

integer

Unique tenant ID.

name

string

School name.

slug

string

URL-safe unique identifier.

is_active

boolean

Whether the tenant is active. Defaults to true.

logo

string | null

Relative storage path to the logo file. null until a logo is uploaded.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-updated timestamp.

logo_url

null

Always null on creation. Upload a logo separately via POST /api/tenants/logo.

director

object

The newly created director user, with tenant_id set and the director role assigned.

Example

curl -s -X POST https://your-cole-api.test/api/tenants \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 2|superAdminToken..." \
  -d '{
    "name": "Colegio Lincoln",
    "slug": "lincoln",
    "director_name": "Carlos Mendoza",
    "director_email": "carlos@lincoln.edu",
    "password": "securePass1"
  }'

{
  "tenant": {
    "id": 3,
    "name": "Colegio Lincoln",
    "slug": "lincoln",
    "is_active": true,
    "logo": null,
    "created_at": "2026-04-02T10:00:00.000000Z",
    "updated_at": "2026-04-02T10:00:00.000000Z"
  },
  "logo_url": null,
  "director": {
    "id": 5,
    "name": "Carlos Mendoza",
    "email": "carlos@lincoln.edu",
    "tenant_id": 3,
    "created_at": "2026-04-02T10:00:00.000000Z",
    "updated_at": "2026-04-02T10:00:00.000000Z"
  }
}

GET /api/tenants

Returns an array of all tenants in the system. Each item in the array includes an appended logo_url field pointing to the publicly accessible logo image. Authentication required: Authorization: Bearer <token> — role super-admin

Example

curl -s -X GET https://your-cole-api.test/api/tenants \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 2|superAdminToken..."

[
  {
    "id": 1,
    "name": "Colegio San Marcos",
    "slug": "san-marcos",
    "is_active": true,
    "logo": "tenants/tenant_1.png",
    "logo_url": "https://your-cole-api.test/storage/tenants/tenant_1.png",
    "created_at": "2026-04-01T09:00:00.000000Z",
    "updated_at": "2026-04-05T14:30:00.000000Z"
  },
  {
    "id": 3,
    "name": "Colegio Lincoln",
    "slug": "lincoln",
    "is_active": true,
    "logo": null,
    "logo_url": null,
    "created_at": "2026-04-02T10:00:00.000000Z",
    "updated_at": "2026-04-02T10:00:00.000000Z"
  }
]

GET /api/tenants/

Returns a single tenant by its numeric ID. Authentication required: Authorization: Bearer <token> — role super-admin

Path parameters

integer

required

The numeric ID of the tenant to retrieve.

Response `200 OK`

data

object

The tenant record.

logo_url

string | null

Fully qualified URL to the tenant’s logo, or null if no logo has been uploaded.

Example

curl -s -X GET https://your-cole-api.test/api/tenants/3 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 2|superAdminToken..."

{
  "data": {
    "id": 3,
    "name": "Colegio Lincoln",
    "slug": "lincoln",
    "is_active": true,
    "logo": null,
    "created_at": "2026-04-02T10:00:00.000000Z",
    "updated_at": "2026-04-02T10:00:00.000000Z"
  },
  "logo_url": null
}

DELETE /api/tenants/

Permanently deletes a tenant. If the tenant has a logo stored on disk, it is removed from the public storage disk before the database record is deleted. Authentication required: Authorization: Bearer <token> — role super-admin

This operation is irreversible. Deleting a tenant removes its record from the database along with any associated logo file. Dependent data (users, academic periods, etc.) may also be cascade-deleted depending on foreign key constraints.

Path parameters

integer

required

The numeric ID of the tenant to delete.

Response `200 OK`

success

boolean

true when the tenant was successfully deleted.

message

string

Confirmation string. Example: "Tenant eliminado correctamente".

Example

curl -s -X DELETE https://your-cole-api.test/api/tenants/3 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 2|superAdminToken..."

{
  "success": true,
  "message": "Tenant eliminado correctamente"
}

Director Tenant Management

Directors cannot see or modify other tenants. They operate exclusively on the tenant they belong to, identified automatically from the tenant_id field on their user record.

GET /api/my-tenant

Returns the authenticated director’s own tenant record along with its logo URL. Authentication required: Authorization: Bearer <token> — role director

Response `200 OK`

data

object

The director’s tenant record.

logo_url

string | null

Fully qualified URL to the tenant’s logo file, or null if no logo has been uploaded yet.

Example

curl -s -X GET https://your-cole-api.test/api/my-tenant \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..."

{
  "data": {
    "id": 3,
    "name": "Colegio Lincoln",
    "slug": "lincoln",
    "is_active": true,
    "logo": "tenants/tenant_3.png",
    "created_at": "2026-04-02T10:00:00.000000Z",
    "updated_at": "2026-04-06T08:00:00.000000Z"
  },
  "logo_url": "https://your-cole-api.test/storage/tenants/tenant_3.png"
}

POST /api/tenants/logo

Uploads or replaces the logo for the authenticated director’s tenant. The file is stored on the public disk under tenants/tenant_{id}.{ext}. Any previously stored logo is deleted before the new file is saved. Authentication required: Authorization: Bearer <token> — role director

This endpoint expects a multipart/form-data request, not JSON. Set your Content-Type to multipart/form-data or use a form upload client.

Request body (multipart/form-data)

logo

file

required

Image file to use as the tenant logo. Accepted MIME types: image/png, image/jpg, image/jpeg. Maximum size: 2 MB (2048 KB).

Response `200 OK`

success

boolean

true on a successful upload.

data

object

The updated tenant record, including the new logo path.

logo_url

string

Fully qualified URL to the newly uploaded logo.

Example

curl -s -X POST https://your-cole-api.test/api/tenants/logo \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..." \
  -F "logo=@/path/to/logo.png"

{
  "success": true,
  "data": {
    "id": 3,
    "name": "Colegio Lincoln",
    "slug": "lincoln",
    "is_active": true,
    "logo": "tenants/tenant_3.png",
    "created_at": "2026-04-02T10:00:00.000000Z",
    "updated_at": "2026-04-06T08:30:00.000000Z"
  },
  "logo_url": "https://your-cole-api.test/storage/tenants/tenant_3.png"
}

PUT /api/tenants

Updates the name and slug of the authenticated director’s tenant. The slug uniqueness check excludes the current tenant so a director can re-submit their existing slug without a conflict error. Authentication required: Authorization: Bearer <token> — role director

Request body

name

string

required

New name for the tenant. Example: "Colegio Lincoln Internacional".

slug

string

required

New URL-safe identifier. Must be unique across all tenants, excluding the current tenant’s existing slug.

Response `200 OK`

success

boolean

true on a successful update.

data

object

The updated tenant record.

logo_url

string | null

Fully qualified logo URL, or null if no logo has been uploaded.

Example

curl -s -X PUT https://your-cole-api.test/api/tenants \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..." \
  -d '{
    "name": "Colegio Lincoln Internacional",
    "slug": "lincoln-int"
  }'

{
  "success": true,
  "data": {
    "id": 3,
    "name": "Colegio Lincoln Internacional",
    "slug": "lincoln-int",
    "is_active": true,
    "logo": "tenants/tenant_3.png",
    "created_at": "2026-04-02T10:00:00.000000Z",
    "updated_at": "2026-04-06T09:00:00.000000Z"
  },
  "logo_url": "https://your-cole-api.test/storage/tenants/tenant_3.png"
}

Module Sub-endpoints (super-admin)

Modules represent optional feature sets that can be enabled or disabled per tenant. When a tenant is created, all available modules are attached automatically in an inactive state. The super-admin uses these endpoints to control which modules a given school can access. All module sub-endpoints require: Authorization: Bearer <token> — role super-admin

GET /api/tenants//modules

Returns all modules currently attached to a tenant, including the activation status for each.

Path parameters

tenantId

integer

required

The ID of the tenant whose modules you want to list.

Response `200 OK`

Returns an array of module objects, each with the following fields:

integer

Module ID.

codigo

string

Short code for the module. Example: "ACADEMICO".

nombre

string

Human-readable module name.

descripcion

string

Brief description of the module.

activo

boolean

Whether the module is currently active for this tenant.

Example

curl -s -X GET https://your-cole-api.test/api/tenants/3/modules \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 2|superAdminToken..."

[
  {
    "id": 1,
    "codigo": "ACADEMICO",
    "nombre": "Módulo Académico",
    "descripcion": "Gestión de cursos, materias y calificaciones",
    "activo": true
  },
  {
    "id": 2,
    "codigo": "ASISTENCIA",
    "nombre": "Módulo de Asistencia",
    "descripcion": "Control de asistencia de estudiantes",
    "activo": false
  }
]

POST /api/tenants//modules

Assigns a module to a tenant and sets it as active. Uses syncWithoutDetaching, so calling this on a module that is already attached will simply update its status to active.

Path parameters

tenantId

integer

required

The ID of the tenant to assign the module to.

Request body

module_id

integer

required

The ID of the module to assign. Must exist in the modules table.

Response `200 OK`

message

string

Confirmation string. Example: "Módulo asignado correctamente.".

Example

curl -s -X POST https://your-cole-api.test/api/tenants/3/modules \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 2|superAdminToken..." \
  -d '{ "module_id": 2 }'

{
  "message": "Módulo asignado correctamente."
}

DELETE /api/tenants//modules/

Detaches a module from a tenant entirely, removing the pivot record.

Path parameters

tenantId

integer

required

The ID of the tenant.

moduleId

integer

required

The ID of the module to remove.

Response `200 OK`

message

string

Confirmation string. Example: "Módulo removido correctamente.".

Example

curl -s -X DELETE https://your-cole-api.test/api/tenants/3/modules/2 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 2|superAdminToken..."

{
  "message": "Módulo removido correctamente."
}

PATCH /api/tenants//modules//activate

Sets the activo pivot flag to true for the specified module on the given tenant. The module must already be attached.

Path parameters

tenantId

integer

required

The ID of the tenant.

moduleId

integer

required

The ID of the module to activate.

Response `200 OK`

message

string

Confirmation string. Example: "Módulo activado correctamente.".

Example

curl -s -X PATCH https://your-cole-api.test/api/tenants/3/modules/2/activate \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 2|superAdminToken..."

{
  "message": "Módulo activado correctamente."
}

PATCH /api/tenants//modules//deactivate

Sets the activo pivot flag to false for the specified module on the given tenant.

Path parameters

tenantId

integer

required

The ID of the tenant.

moduleId

integer

required

The ID of the module to deactivate.

Response `200 OK`

message

string

Confirmation string. Example: "Módulo desactivado correctamente.".

Example

curl -s -X PATCH https://your-cole-api.test/api/tenants/3/modules/2/deactivate \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 2|superAdminToken..."

{
  "message": "Módulo desactivado correctamente."
}

Auth

Administration

Academic Management

Teaching

Parent & Student Portal

Circulares

Documentation Index

​Tenant CRUD (super-admin)

​POST /api/tenants

​Request body

​Response 200 OK

​Example

​GET /api/tenants

​Example

​GET /api/tenants/

​Path parameters

​Response 200 OK

​Example

​DELETE /api/tenants/

​Path parameters

​Response 200 OK

​Example

​Director Tenant Management

​GET /api/my-tenant

​Response 200 OK

​Example

​POST /api/tenants/logo

​Request body (multipart/form-data)

​Response 200 OK

​Example

​PUT /api/tenants

​Request body

​Response 200 OK

​Example

​Module Sub-endpoints (super-admin)

​GET /api/tenants//modules

​Path parameters

​Response 200 OK

​Example

​POST /api/tenants//modules

​Path parameters

​Request body

​Response 200 OK

​Example

​DELETE /api/tenants//modules/

​Path parameters

​Response 200 OK

​Example

​PATCH /api/tenants//modules//activate

​Path parameters

​Response 200 OK

​Example

​PATCH /api/tenants//modules//deactivate

​Path parameters

​Response 200 OK

​Example

Build docs developers (and LLMs) love

Tenant CRUD (super-admin)

POST /api/tenants

Request body

Response `200 OK`

Example

GET /api/tenants

Example

GET /api/tenants/

Path parameters

Response `200 OK`

Example

DELETE /api/tenants/

Path parameters

Response `200 OK`

Example

Director Tenant Management

GET /api/my-tenant

Response `200 OK`

Example

POST /api/tenants/logo

Request body (multipart/form-data)

Response `200 OK`

Example

PUT /api/tenants

Request body

Response `200 OK`

Example

Module Sub-endpoints (super-admin)

GET /api/tenants//modules

Path parameters

Response `200 OK`

Example

POST /api/tenants//modules

Path parameters

Request body

Response `200 OK`

Example

DELETE /api/tenants//modules/

Path parameters

Response `200 OK`

Example

PATCH /api/tenants//modules//activate

Path parameters

Response `200 OK`

Example

PATCH /api/tenants//modules//deactivate

Path parameters

Response `200 OK`

Example