Management API

This API allows accounts of type Owner to automate the creation and management of their Agencies and Agents. All requests to these endpoints must be authenticated with the Owner's API Key.

Authentication

All requests to the Management API must include the X-Owner-API-Key header with the Owner's API Key. This API is primarily intended for server-to-server integrations.

Header Example

X-Owner-API-Key: your_owner_api_key

CORS Note: If you are calling these endpoints from a frontend in a browser, make sure the server allows the X-Owner-API-Key header in the preflight request (CORS Access-Control-Allow-Headers). For typical recommended use (server-to-server), this is not necessary.

Agency Endpoints

POST /api/management/agencies

Creates a new Agency type account under the authenticated Owner.

Request Body

application/json

{
    "name": "Demo Travel Agency",
    "email": "contact@demoagency.com",
    "password": "a_strong_password",
    "consumes_owner_tokens": true,
    "contact_person": "Ana Garcia",
    "phone_number": "+34123456789",
    "address_line1": "123 Fake Street",
    "city": "Madrid",
    "postal_code": "28001",
    "country": "ES",
    "notes": "Optional notes"
}

Notes:

consumes_owner_tokens is a boolean and defaults to true.
The other fields shown are optional and can be omitted.

Successful Response (201 Created)

Returns the complete object of the created agency, including its own API Key.

application/json

{
    "id": 15,
    "name": "Demo Travel Agency",
    "email": "contact@demoagency.com",
    "api_key": "a_new_api_key_for_the_agency",
    "account_type": "agency",
    "owner_propietario_id": 1
    // ... other fields
}

Common Errors

400 – Validation (missing required fields or invalid types).
409 – Duplicate (email already exists / "in use").
500 – Internal error.

Agent Endpoints

POST /api/management/agents

Creates an Agent that reports directly to the authenticated Owner (not to an Agency).

Request Body

application/json

{
    "name": "Owner Agent",
    "username": "optional_for_login",
    "password": "required_if_username_is_set"
}

Successful Response (201 Created)

application/json

{
    "id": 101,
    "name": "Owner Agent",
    "username": "owner.agent",
    "token": "unique_token",
    "is_active": true,
    "created_at": "2025-05-12T10:15:30Z"
}

Common Errors

400 – Missing name, or username is sent without a password.
409 – Duplicate (username "already exists/in use").
500 – Internal error.

POST /api/management/agencies/<agency_id>/agents

Creates an Agent (employee token) for a specific Agency of the Owner. The agency_id must belong to an Agency owned by the authenticated Owner.

Request Body

application/json

{
    "name": "Support Agent (Demo Agency)",
    "username": "support.agent.demo",
    "password": "password_for_the_agent"
}

Successful Response (201 Created)

Returns the created agent object, including its unique token.

application/json

{
    "id": 101,
    "name": "Support Agent (Demo Agency)",
    "username": "support.agent.demo",
    "token": "a_unique_token_for_this_agent",
    "is_active": true,
    "created_at": "2025-05-12T10:15:30Z",
    "agency_id": 15,
    "agency_name": "Demo Travel Agency"
}

Common Errors

400 – Validation (missing fields or invalid types).
404 – The agency_id does not exist or does not belong to the authenticated Owner.
409 – Duplicate (username "already exists/in use").
500 – Internal error.