Webservice Setup

Configure an OTOBO GenericInterface REST webservice before using the Python SDK — required for all API calls.

Webservice setup — OTOBO

The Python SDK cannot talk to OTOBO until a GenericInterface REST webservice exists.
pip install otobo only installs the client library. Every OTOBOClient call goes through URLs like:

https://your-otobo-server/Webservice/{webservice_name}/{operation_path}

If no webservice is configured, you will see HTTP 404 errors, authentication failures, or GenericInterface error responses — not Python import errors.

What you need before writing Python code

The SDK ships a setup wizard that creates all of this for you. Manual configuration in the OTOBO admin UI is also possible.

Recommended: otobo-cli setup-system

Run this on the OTOBO host or inside the OTOBO Docker container.

1. Install the package

pip install otobo

2. Start the wizard

otobo-cli setup-system

The CLI auto-detects standalone OTOBO at /opt/otobo/bin/otobo.Console.pl or Docker containers named otobo-web-1 / otobo_web_1.

If detection fails, run the command on the machine where otobo.Console.pl is available.

3. Create an API user (recommended)

The wizard asks whether to create a dedicated user. Choose yes unless you already have an agent account reserved for integrations.

Store the password securely (environment variable or secret manager). Never commit it to git.

4. Configure the webservice

The wizard generates a GenericInterface YAML file and imports it via:

otobo.Console.pl Admin::WebService::Add --name <name> --source-path <file.yml>

For Docker installations, the CLI copies the YAML into the container before importing.

5. Default operation paths

When you use the CLI wizard with default settings, map operations in Python like this:

These path names must match exactly what is configured in the webservice. If you chose different names during setup, use those names instead.

6. Connect the SDK

from otobo import OTOBOClient, BasicAuth, ClientConfig, TicketOperation

client = OTOBOClient(
    ClientConfig(
        base_url="https://your-otobo-server",
        webservice_name="PythonClientWebService",
        operation_url_map={
            TicketOperation.CREATE: "ticket-create",
            TicketOperation.GET: "ticket-get",
            TicketOperation.SEARCH: "ticket-search",
            TicketOperation.UPDATE: "ticket-update",
        },
    )
)
client.login(BasicAuth(user_login="python-client-user", password="YOUR_PASSWORD"))

Replace base_url with your public OTOBO URL (no trailing slash). Use the webservice name and paths from your setup.

Manual setup in the OTOBO admin UI

Use this when you cannot run the CLI on the server, or when you need to attach the SDK to an existing webservice.

Step 1 — Open web services

1. Log in to OTOBO as an administrator.
2. Go to Admin → Web Services.
3. Click Add web service.

Step 2 — Provider configuration

1. Set Name to the value you will use in ClientConfig.webservice_name (for example PythonClientWebService).
2. Set Type to Provider (incoming REST requests from your Python app).
3. Under Transport, choose HTTP::REST.

Step 3 — Add provider operations

Add one operation per SDK method. Use these backend operation types and route paths:

Enable Include ticket data for each operation (the SDK expects full ticket payloads).

Map the route for each operation in the transport RouteOperationMapping section so the URL path matches the operation name.

Step 4 — Agent permissions

Ensure the agent account you pass to BasicAuth:

• Can log in to OTOBO.
• Has read/write access to the queues you create tickets in.
• Is allowed to use the webservice (if you configured user restriction on the webservice).

Step 5 — Save and test

Save the webservice. Test with curl before switching to Python:

curl -X GET "https://your-otobo-server/Webservice/PythonClientWebService/ticket-get?UserLogin=python-client-user&Password=YOUR_PASSWORD&TicketID=1"

Adjust query parameters to match your webservice mapping. A valid response (or a structured GenericInterface error) confirms the endpoint is reachable.

Manual import via console (YAML)

If you have a webservice YAML file, import it on the OTOBO server:

/opt/otobo/bin/otobo.Console.pl Admin::WebService::Add \
  --name PythonClientWebService \
  --source-path /path/to/webservice.yml

Inside Docker:

docker exec -it otobo-web-1 /opt/otobo/bin/otobo.Console.pl Admin::WebService::Add \
  --name PythonClientWebService \
  --source-path /opt/otobo/var/webservices/webservice.yml

Troubleshooting

Next steps

Once the webservice responds, continue with Getting started and Working with tickets.