Authentication

Authentification

Before secure requests can be made, a valid authentication feature - in future called Token - is required. Authentication takes place via API call with username and password key and returns a JWT token if successful.

!!! important "Important" The token must be used for all requests except the login. For the use of the token see Using a token

The following information is required for authentication:

  • Server-URL
  • Username / Email
  • Password

The following information is also required for further calls.

  • Municipality-ID(s)
  • Property-ID(s)
  • Landlord-ID(s)

This information can be called directly via get_config after authentication.

Generating a token

1
POST api /token/
Field Data type Explanation
username string Username or email address
password string the corresponding password

Feature

Authentication can be passed as 'application/x-www-form-urlencoded' in addition to JSON or XML - better known as form data. This allows for an interactive login to the system via e.g. an HTML form or a third-party application.

Examples

Request
1
{ "username": "m.mustermann", "password": "5bed8a17a5f780aa3b541e41c62416a64" }

1
2
3
4
<root>
    <username>m.mustermann</username>
    <password>5bed8a17a5f780aa3b541e41c62416a64</password>
</root>
Response
1
{ "token": "eJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ...<abgeschnitten>" }

1
2
3
4
<?xml version="1.0" encoding="utf-8"?>
<root>
  <token>eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.....<!--abgeschnitten--></token>
</root>

Generating a token

The token is passed in the HTTP header “Authorization” with every query. Before the token generated in the first step

HTTP Header Authorization

Prefix: JWT

Example:

1
Authorization: JWT eyJhbGciOiJIUzI1NiIeyJ4554dscvd499dfcc....

!!! note Please pay attention to the prefix JWT and the space between the prefix and the actual token. [PRÄFIX|LEERSTELLE|TOKEN]


Code Examples

Requesting a token

1
2
3
4
5
# pip3 install requests
 import requests 
 payload = { 'username':'demo', 'password':'demo', }
 r = requests.post('https://<API_URL>/api/token/',data=payload) server_response_json = r.json() 
 jwt_token = server_response_json.get('token') # From the server_response object extract the string value from &ldquo;token&rdquo; print(jwt_token) #<str>: eJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Passing a token in the header

1
2
3
4
5
# pip3 install requests
 import requests payload = { # any data } # variable jwt_token from previous example 
 headers = { 'authorization': 'JWT %s' % jwt_token # "JWT eJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." } #Here the header is passed as well 
 r = requests.post('https://<API_URL>/<anfrage>/',data=payload,headers=headers) 
 server_response_json = r.json() # ...

Meta-Object

In addition to a matching Auth token, a meta object is required for all authenticated requests. This object identifies the query and passes a context for the call.

In this way, gemeinde, vermieter and objekt indicate for which municipality and which landlord and object of the municipality the call is used.

JSON-Schema: /api/meldeschein/schema/meta/

!!! warning "Note" The meta object cannot be passed alone. It always belongs to a further call (see corresponding chapter)

Parameters

Field Data type required Description
Municipality int true The ID of the municipality to be posted
landlord int true The ID of the landlord to be posted
objekt int true The ID of the landlord to be posted
description string false An optional reference for booking

Examples

Request
1
{ "meta": { "description": "An example posting", "vermieter": 1, "objekt": 1, "gemeinde": 1 } // Additional data }

1
2
3
4
5
6
7
<?xml version="1.0" encoding="utf-8"?>
<meta>
    <description>An example posting</description>
    <vermieter>1</vermieter>
    <objekt>1</objekt>
    <gemeinde>1</gemeinde>
</meta><!-- weitere Daten -->