Authenticate to Znuny / OTRS REST API

Learn in this article what options exist to authentication against the Znuny / OTRS / OTOBO WebService REST APIs.
You will find also cURL examples for better understanding.

In the previous articles Access Znuny & OTRS API via REST, Znuny & OTRS REST API Routes we guide you thru the configuration steps of REST API in the role of the service provider. If you followed the steps your system is accessible via the new REST API and awaiting now your cURL access described in this article.

Authentication

As written in Znuny & OTRS REST API Routes we can access our REST API via:

http://{{znunyHostName}}/otrs/nph-genericinterface.pl/Webservice/Ticket%20REST%20API

Authentication types

There are two common authentication methods:

1. UserLogin & Password
   Authentication of each request with UserLogin and Password
   
   OR
   
2. Session Auth (recommended)
   Session authentication with UserLogin and Password to create Session, following with authentication of all next calls with obtained SessionID.

Authentication information is sent with request data as options. The data format is given by used HTTP method (i.e. for GET requests it has to be mentioned in Query string; for POST&PATCH in JSON Data). Alternatively starting from the version of Znyny 6.1.2 the authentication information can also be posted via X-OTRS-Header-(UserLogin|CustomerUserLogin|SessionID|Password).

Too complicated? No issue, read on. It will be clear later

Example: Create a Ticket with user & password authenticated request

This is the most obvious way, many will choose. Anyway, the recommended way is to use session-based authentication.

REST API create a ticket with user & password in body data

Below you can see an example of user/password authenticated request creating a Ticket:

Request:

POST http://{{FQDN}}/otrs/nph-genericinterface.pl/Webservice/Ticket%20REST%20API/Ticket?

Data in the body:

{
"data" : {
    "UserLogin":"{{user}}",
    "Password":"{{pass}}",
    "Ticket":{
        "Title":"Ticket created via REST API - minimal content",
        "Queue":"Raw",
        "StateID": 1 ,
        "PriorityID": 3,
        "CustomerUser":"{{CustomerUser}}"
    },
    "Article":{
        "CommunicationChannel":"Email",
        "Subject":"Test Article created with new Ticket via REST API type Email",
        "Body":"email body.",
        "ContentType":"",
        "Charset":"utf-8",
        "MimeType":"text/plain"
    }
  }
}

Variables:

When converted into cURL the example of UserLogin&Password authenticated creation of a ticket looks like this:

curl --location --request POST 'http://localhost/otrs/nph-genericinterface.pl/Webservice/Ticket%20REST%20API/Ticket' 
--header 'Content-Type: application/json' 
--data-raw '{
    "UserLogin":"userXYZ",
    "Password":"plain-text-password",
    "Ticket":{
        "Title":"Ticket created via REST API - minimal content",
        "Queue":"Raw",
        "StateID": 1 ,
        "PriorityID": 3,
        "CustomerUser":"CustomerUser"
    },
    "Article":{
        "CommunicationChannel":"Email",
        "Subject":"Test Article created with new Ticket via REST API type Email",
        "Body":"email body.",
        "ContentType":"",
        "Charset":"utf-8",
        "MimeType":"text/plain"
    }
}'

REST API to create a ticket with user & password in query parameter (absolutely NOT recommended)

This example you will find in many examples around OTRS / Znuny / OTOBO. But exactly this way is absolutely the totally wrong way in terms of security.

Since you will pass your user and password to access the REST API in the query URL, it will be logged into all access-log files of your webservers. And thus whoever has access to these logs, has also some critical user & password information of Znuny, OTRS, or OTOBO users.

So simply: DO NOT USE THIS WAY IF YOU HAVE ANY SENSE FOR SECURITY FOR YOU OR YOUR CLIENT!!!

To shorten the description here is only a sample cURL, as said DO NOT use it

curl --location --request POST 'http://localhost/otrs/nph-genericinterface.pl/Webservice/Ticket REST API/Ticket?UserLogin=userXYZ&Password=plain-text-password' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Ticket":{
        "Title":"Ticket created via REST API - minimal content",
        "Queue":"Raw",
        "StateID": 1 ,
        "PriorityID": 3,
        "CustomerUser":"CustomerL"
    },
    "Article":{
        "CommunicationChannel":"Email",
        "Subject":"Test Article created with new Ticket via REST API type Email",
        "Body":"email body.",
        "ContentType":"",
        "Charset":"utf-8",
        "MimeType":"text/plain"
    }
}'

Example: Create Ticket using SessionID authentication (recommended)

This method of authentication is recommended and also a very common standard in terms of API access. Also, this method is better in terms of generating less load on OTRS, Znuny, or OTOBO, since you do the authentication only once and all subsequent queries are already pre-authenticated.

To access the API you have to process these steps:

1. Create Session and get SessionID
2. Create Ticket using SessionID authentication
3. reuse the SessionID for any later API accesses
4. refresh SessionID if the session expired (which will be explained in a different article)

Create Session and get SessionID

Request:

curl --location --request POST 'http://localhost/otrs/nph-genericinterface.pl/Webservice/Ticket%20REST%20API/Session' 
--header 'Content-Type: application/json' 
--data-raw '{
    "UserLogin":"userXYZ",
    "Password":"plain-text-password"
}'

Response:

{
    "SessionID": "Yx9TilyRyGveitmMKrdBy2Q8oqKqA4U2"
}

Create Ticket using SessionID authentication

CURL example of the SessionID authenticated creation of a ticket:

curl --location --request POST 'http://localhost/otrs/nph-genericinterface.pl/Webservice/Ticket%20REST%20API/Ticket' 
--header 'Content-Type: application/json' 
--data-raw '{
    "SessionID":"Yx9TilyRyGveitmMKrdBy2Q8oqKqA4U2",
    "Ticket":{
        "Title":"Ticket created via REST API - minimal content",
        "Queue":"Raw",
        "StateID": 1 ,
        "PriorityID": 3,
        "CustomerUser":"CustomerL"
    },
    "Article":{
        "CommunicationChannel":"Email",
        "Subject":"Test Article created with new Ticket via REST API type Email",
        "Body":"email body.",
        "ContentType":"",
        "Charset":"utf-8",
        "MimeType":"text/plain"
    }
}'

Related articles

To learn more about OTRS & Znuny REST API routes and request options please see Znuny & OTRS REST API URLs & Routes.

To learn how to setup the REST API in OTRS & Znuny installation please see Access Znuny & OTRS API via REST.