This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation

We are continuously working on omniac Business, so the documentation and the API is subject to change. We keep you updated on changes.

1 - Getting Started

This section outlines the setup for omniac Business and how to start the monitoring.

This section outlines the steps to get started with omniac Business, including how to start the monitoring of a user, how to query a users alerts and how to query a users data.

1.1 - Authentication

API authorization instructions for omniac Business.

Our API supports two types of authentication. API keys are easy und straight forward to use, but also less secure since they can be affected by a man-in-the-middle-attack. The more secure approach is to use OAuth with client credential flow. This way we are able to provide you an identity or also to use your identity-provider.

API Key

To use an API Key we need to enable this feature within your tenant. The provided key must be sent with each request using X-API-KEY Header.

curl --request GET \
  --url https://api.omniac.de/v1/tenant \
  --header 'X-API-KEY: <<API KEY>>'

OAuth client credential

Coming soon

1.2 - Basic Data Structure

Information about the data structure and associated terminology.

This section contains a brief introduction into the data. Every tenant will have multiple profiles, within a profile there will be a list of attributes and alerts.

- * tenant
  |- settings
  |
  |- profiles
     |- profile
     |  |- alerts
     |  |- attributes
     |
     |- profile
     |  |- alerts
     |  |- attributes

1.3 - OpenAPI Generator

Instructions for using openapi-generators.

OpenAPI Generator

We recommend using the official OpenAPI Generator to generate the client code. The generator can be found at OpenAPI Generator. It offers various options for generating client libraries in different programming languages. It generates code based on the OpenAPI specification such as functions to invoke the endpoints and types for the request and response bodies.

Client Generation Steps

  1. Download the OpenAPI Specification: Obtain the OpenAPI specification file for omniac Business. This file is YAML format and describes the API endpoints, request parameters, and response structures.
  2. Install OpenAPI Generator: If you haven’t already, install the OpenAPI Generator CLI tool. Consult the OpenAPI Generator documentation for installation instructions.
  3. Generate the Client: Use the OpenAPI Generator CLI to generate the client code. The command typically looks like this: 
    openapi-generator-cli generate -i path/to/openapi.yaml -g <language> -o path/to/output/directory
    Replace <language> with the desired programming language (e.g., python, java, javascript, etc.) and specify the path to the OpenAPI specification file and the output directory where the generated client code will be saved.

1.4 - Receive Push Alerts

How to receive notifications via the Push-API .

To get notified even faster, we provide a push api for new alerts. As soon as incidents are found for certain attributes, we will publish the alert into your system. This is done over a HTTP-call. The delivery will marked as done on our side as soon as your api returns a 2xx http status code.

To use this feature, you need to contact us, so we can enable the feature for your tenant.

A default body of this request looks like this:

{
  "_id": {
    "$oid": "REDACTED"
  },
  "is_read": false,
  "profile_id": {
    "$oid": "REDACTED"
  },
  "enrollment_id": {
    "$oid": "REDACTED"
  },
  "enrollment_provider": "",
  "alert_id": "REDACTED",
  "client_id": "REDACTED",
  "alert_flow": "retrospective",
  "masked_values": [
    {
      "name": "password",
      "value": "",
      "passwordcleartext": false
    },
    {
      "name": "email",
      "value": "t******@ex*****e.com",
      "passwordcleartext": null
    },
    {
      "name": "domain",
      "value": "ex*****e.com",
      "passwordcleartext": null
    },
    {
      "name": "network_ip",
      "value": "12*****.1",
      "passwordcleartext": null
    },
    {
      "name": "username",
      "value": "********",
      "passwordcleartext": null
    }
  ],
  "password_last_characters": "",
  "breach_category_locale": "Spiele",
  "description_type": "code_standard",
  "recommendation": "Ändere dein Passwort für das betroffene Kundenkonto. Überprüfe schnell alle anderen Dienste, bei denen du das gleiche oder ein ähnliches Passwort benutzt. Sei aufmerksam in Bezug auf ungewöhnliche Aktivitäten rund um deine Identität",
  "description": "Deine Daten wurden am DATUM im WEBSEITE-Datenleck veröffentlicht.",
  "name": "WEBSEITE",
  "source": "darkweb",
  "breach_record_exposure_score": "Very Low",
  "date_register": {
    "$date": "2014-01-30T00:00:00.000Z"
  },
  "creation_date": {
    "$date": "2025-09-30T12:15:13.883Z"
  },
  "done": false,
  "done_date": {
    "$date": {
      "$numberLong": "-62135596800000"
    }
  },
  "type": "darkweb"
}

1.5 - Encryption in the client

Client-side normalization, encryption, and hashing

In addition to the option of sending the data to be monitored in plain text to omniac Business, we also offer the option of receiving the data already normalized, encrypted, and hashed. The latter is also the method we recommend, as it ensures that your users’ personal attributes never leave your company context in plain text. The processing steps required for this must be identical to those we perform before using the data to search our data leak database. This procedure is briefly explained below.

Retrieve tenant

In your tenant, you will find all the necessary information for normalization, encryption, and hashing. In the “available_attributes” field, you will find the normalization rules, in the “hash_algorithm” field the hash function to be used, and in the “encryption_key” field the public key to encrypt the data. Each of these steps is now briefly explained.

Example: Email

The normalization step must be performed at the beginning and before any further processing. Let’s look at the example of email (found in the tenant’s “available_attributes”):

{
    "key": "email",
    "encrypted": true,
    "split": false,
    "normalize": [
        "DeleteQuotationMarks",
        "DeleteTrailingComma",
        "UnicodeNormalization",
        "Strip",
        "Lowercase"
    ],
    "mask": {
        "task": "email",
        "begin": 0,
        "end": 0
    }
},

All of the following steps are performed on the normalised version of the email. Next comes hashing. The algorithm is specified in the tenant, but currently it is always SHA-256. Encryption is not required for every attribute (see boolean field encrypted). If encrypted=true the PKCS1 algorithm is used. Here is an example implementation in Go:

func EncryptWithPublicKey(pubKey string, data string) (string, error) {
	publicKeyBytes, err := base64.StdEncoding.DecodeString(pubKey)
	if err != nil {
		return "", errors.New("failed to decode public key: " + err.Error())
	}

	rsaPublicKey, err := ParseRsaPublicKeyFromPemStr(string(publicKeyBytes))
	if err != nil {
		return "", errors.New("ParseRsaPublicKey: " + err.Error())
	}
	rng := rand.Reader
    ciphertext, err := rsa.EncryptPKCS1v15(rng, rsaPublicKey, []byte(data))
	if err != nil {
		return "", errors.New("failed to encrypt data: " + err.Error())
	}

	// Encode the encrypted data to base64 for easy transmission or storage
	return base64.StdEncoding.EncodeToString(ciphertext), nil
}

Example: Name (split attribute)

If the “split” parameter is set in the AttributConfig, omniac Business expects that after normalisation, the values will be separated at each space and the resulting parts will be normalised and hashed again individually. However, encryption still happens on the entire value. Finally, the hashed values are transmitted to omniac Business as a string separated by commas. Here is an example:

{
    "key": "name",
    "encrypted": true,
    "split": true,
    "normalize": [
        "DeleteQuotationMarks",
        "DeleteTrailingComma",
        "ReplaceSymbols",
        "DeleteConsecutiveSpaces",
        "UnicodeNormalization",
        "Strip",
        "Lowercase"
    ],
    "mask": {
        "task": "",
        "begin": 0,
        "end": 0
    }
},

If, for example, the name is to be monitored, the following steps are necessary because split=true. Name example: “Max Mustermann”

  1. Normalisation of the entire string (“max mustermann”)
  2. Encryption of the normalised string (“Q2CWI6xZ6r2QsS/tJCARqzFWEXh+aeRuClgaX4AzMrNAXrgyQcfq6/lYsCGvSPVa1jTWF7zd4fmi2AMh3DbirRNpfCJNNZcW2mE1Iw0EhilpYen6nYAMPtxb5zHhsb2DfaKr0qOFal1zIjDM+KiAbLaiOF+wTajGmH/3Bt2rwvK30/qDta3u3oplKzLVNqaoWpqGqiv0cKx9ytday8YqxqbqNcGZf1ztZVUAxkS4M0UHsVHVnHDK6ADcZoz2scdJU9nwipb0C2dXGePlE/hBBttkzq6lR2vExfIbjTQ+QEhzQiUdvz9WeuckHLRG8jGhMnSpIUZ9Pt/w2H1qAoEN0A==”)
  3. Splitting the string at the spaces ([“max”, “mustermann”])
  4. Normalise the parts ([“max”, “mustermann”])
  5. Hash the parts ([“9baf3a40312f39849f46dad1040f2f039f1cffa1238c41e9db675315cfad39b6”, “e32a370b7912ad78cc6a88fda605a5b3657e9c3b164cee669364aaf3f8cdbb36”])
  6. Merge the hashed parts as a string separated by commas (“9baf3a40312f39849f46dad1040f2f039f1cffa1238c41e9db675315cfad39b6, e32a370b7912ad78cc6a88fda605a5b3657e9c3b164cee669364aaf3f8cdbb36”)

Sending the attributes

While a normal PUT /v1/profiles/:profile_id/attributes call body looks like this:

[
     {
        "type": {
            "key": "name"
        },
        "value": "Max Mustermann",
    },
    {
        "type": {
            "key": "email"
        },
        "value": "test@example.com",
    },
]

we expect the following format for values hashed and encrypted in the client:

[
     {
        "type": {
            "key": "name"
        },
        "value": "M** ******mann",
        "hashed": "9baf3a40312f39849f46dad1040f2f039f1cffa1238c41e9db675315cfad39b6,e32a370b7912ad78cc6a88fda605a5b3657e9c3b164cee669364aaf3f8cdbb36",
        "encrypted": "Q2CWI6xZ6r2QsS/tJCARqzFWEXh+aeRuClgaX4AzMrNAXrgyQcfq6/lYsCGvSPVa1jTWF7zd4fmi2AMh3DbirRNpfCJNNZcW2mE1Iw0EhilpYen6nYAMPtxb5zHhsb2DfaKr0qOFal1zIjDM+KiAbLaiOF+wTajGmH/3Bt2rwvK30/qDta3u3oplKzLVNqaoWpqGqiv0cKx9ytday8YqxqbqNcGZf1ztZVUAxkS4M0UHsVHVnHDK6ADcZoz2scdJU9nwipb0C2dXGePlE/hBBttkzq6lR2vExfIbjTQ+QEhzQiUdvz9WeuckHLRG8jGhMnSpIUZ9Pt/w2H1qAoEN0A=="
    },
    {
        "type": {
            "key": "email"
        },
        "value": "te*****@**ple.com",
        "hashed": "973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b",
        "encrypted": "K/QKpKzdLLGRSayMrqPFqpBCN/vH6fDKWltqNqX1E0ZBLZQEya6rLqg8VTiomyC3hDnp3d+YFHYwXyFpCRjIXQ0uXA8Yz2fZWHnYdLVv5ua2gYAC9huCJmtM89wYBLINPq47gERwHUeiSzVxNk3D6XvwgvGQXd+N+y/A4XC+mhhe603CrC6lzY0N2e7QyQK5YBni9mfr0S+lMVN6CpGqBlnucKGaVXdPn9fBmwWvW3pkA4uoEhRQruD9fdIBFrOy388ctRtrmHFVlP5IWkwXxXas2CpLCarapgULJcO9pG6kG0RqE+NAiKgsZ2Jw3PA0ZLqjp0sIXH3xTzLPNZJ7xQ=="
    },
]

Now the attributes are stored and monitored by us, as in the version in which omniac Business takes over these steps.

2 - Datastructure

This section outlines the data structure within the application.

2.1 - alert

datatype alert

Alerts are notifications generated by omniac Business when breach incidents for certain attributes are detected. These alerts are crucial for maintaining the security and privacy of users’ data. Each alert contains details about the breach incident, including the type of attribute affected, the source, the time it happened, a criticality classification, short standard description of the incident and a recommendation. Depending on what details are required, the alert payload can be individualized.

We provide these alerts via REST in JSON format. As soon as we detect a breach incident we trigger the configured endpoint from the tenant configuration.

A sample alert payload looks like this:

{
    "alert_id": "685e5c371f317d8df6c618a3",
    "alert_flow": "retrospective",
    "masked_values": [
        {
            "name": "bank_account",
            "value": "could not resolve data"
        },
        {
            "name": "credit_card",
            "value": "could not resolve data"
        },
        {
            "name": "iban",
            "value": "could not resolve data"
        },
        {
            "name": "nid",
            "value": "could not resolve data"
        },
        {
            "name": "passport",
            "value": "could not resolve data"
        },
        {
            "name": "driver_license",
            "value": "could not resolve data"
        }
    ],
    "password_last_characters": "",
    "breach_category_locale": "",
    "description_type": "",
    "recommendation": "If the website has customer service or privacy officer contact information, request that any of your personal data be removed immediately.",
    "description": "On 05/24/2023, we discovered this identity information including your names, surnames, emails and addresses that we believe belongs to you from sec.gov/Archives/edgar/Feed/2002/QTR3",
    "name": "sec.gov",
    "source": "",
    "type": "surface",
    "breach_record_exposure_score": "Medium",
    "date_register": "2023-05-18T09:10:36Z",
    "creation_date": "2025-06-27T08:54:15Z",
    "done": false,
    "done_date": "0001-01-01T00:00:00Z"
}

2.2 - attribute

datatype attribute

Attributes are used to store and monitor various personal data of a user. They are stored in a masked, hashed and encrypted way to ensure privacy and security. There are up to 39 attributes available - a detailed list can be found below. Mainitaining attributes is done through the PUT /attributes endpoint. This replaces all attributes with the provided ones so make sure to include existing attributes as well. Old Attributes can be accessed through the GET /profile endpoint.

  • First Name
  • Last Name
  • Mother’s Maiden Name
  • Mother’s Name
  • Email (up to 10 values available)
  • Landline and Mobile Phone Number (up to 10 values available)
  • Address: (up to 10 values available)
    • Street Name
    • City
    • Postal/Zip Code
    • State/Province
  • Date of Birth (DoB)
  • Credit Card Number (up to 10 values available)
  • IP Address (up to 10 values available)
  • Loyalty Program Number (up to 10 values available)
  • Health Insurance Number (up to 10 values available)
  • National Health Service (NHS) Number (UK only)
  • Insurance Policy Number (up to 10 values available)
  • Username (all platforms, up to 10 values available)
  • Gamertag (up to 10 values available)
  • Online Accounts (YouTube, Facebook, Instagram, Google, etc. – approx. 20 different platforms)
  • Bank Account Number (up to 10 values available)
  • IBAN (up to 10 values available)
  • Driver’s License Number (up to 10 values available)
  • National ID Card Number (up to 10 values available)
  • Passport Number (up to 10 values available)
  • Social Security Number (SSN)
  • Tax Identification Number (TIN)
  • Visa Number (up to 10 values available)
  • Crypto Wallet Address (up to 10 values available)

2.3 - profile

datatype profile

A profile holds all the information for one specific user within your tenant. This profile combines a set of attributes that have been saved for a user and the triggered alerts in case breach incidents were detected.

Creating a profile is as simple as issuing a POST request against the profiles endpoint (/v1/profiles). The same endpoint also accepts requests with a profileID (/v1/profiles/{profileID}) with the following methods:

  • GET for retrieving a profile,
  • DELETE for removing a profile and
  • PUT for storing new attributes.

Please consult the openapi spec for in depth request and repsonse documentation.

You can also request all associated profiles for your tenant by issuing a GET request without providing the profileID.

2.4 - tenant

datatype tenant

Tenants represent individual customers or organizations that use the omniac Business service. Each tenant has its own set of users, data, and configurations, allowing for tailored security monitoring and management. Cross tenant access of data is not allowed, ensuring that each tenant’s information remains private and secure.

Configuration

Initially a tenant will be provided to you by omniac Business. You or a representative of omniac Business can then configure the tenant to your needs. The configuration includes:

  • Contact: The contact information (name, email) for one or more contact persons in your organization.
  • Push Endpoint: The URL to which omniac Business will send notifications about alerts.
  • Hash Algorithm: Omniac Business supports hashing either on the client or server side. From a security point of view we highly recommend client side hashing. We use SHA256 as hashing algorithm.
  • Encryption Key: If you choose to encrypt your data, we provide this encryption key. This key is used to encrypt your data before it is sent to omniac Business for monitoring. Please use the RSA PKCS#1 v1.5 algorithm for encryption.
  • Allowed ACLs: You can specify which Access Control Lists (ACLs) are allowed for your tenant. Each ACL config consists of a name and an ACL IP address. This allows you to control which IP addresses can access your tenant’s data and services.
  • Availabe Attributes: Depending on your contract this will be a list of attributes that omniac Business will monitor for your tenant. Each customer/employee can then monitor 0-n attributes. The attributes are defined and maintained by omniac Business.
  • Rate-Limits: Defines how many requests per time are accepted by the omniac Business service for your tenant. This is used to prevent abuse and ensure fair usage of the service. The rate-limits are maintained by omniac Business.

Authentication

To access the omniac Business service, each tenant must authenticate using a unique API key. This key is provided by omniac Business and should be kept secure. The API key is used to identify the tenant and authorize access to the service.

3 - Examples

Here you can find some example implementations.

Within this section you will find some example implementations. We provide examples for the usage of our api and also how to implement the data handling like hashing and encryption.

3.1 - Example Golang

A example for a golang client that enrolls data within our solution

Introduction and project setup

Go (Golang) is a statically typed, compiled programming language developed by Google, known for its simplicity, efficiency, and excellent concurrency support, making it ideal for building scalable web services, APIs, and microservices. To manage project dependencies in Go, you use Go modules. You can initialize a new Go module in your project directory by running the terminal command go mod init <module-name>, where <module-name> is typically your repository URL (e.g., github.com/username/project). This creates a go.mod file that tracks your dependencies. When you import packages and run go mod tidy, Go automatically downloads and manages the required dependencies. Go’s module system ensures reproducible builds and proper version management. You can build your project with go build and run it directly with go run main.go. This approach keeps your projects organized and ensures consistent dependency management across different environments.

Lets go

We highly recommend to use a unix based development environment. This is not only possible by using linux or macOS but also by installing Linux Subsystem for Windows. If you use a plan windows you might need to adapt in certain steps.

Generate API code

For golang we recommend using ogen, to generate client code required to interact with the API.

mkdir omniac-client
cd omniac-client
go mod init github.com/yourusername/omniac-client

Now add the following to your generated go.mod file to add the dependency ogen:

module o4b_client_test

go 1.25.3

tool github.com/ogen-go/ogen/cmd/ogen
require (
    [...]
)

Now run go mod tidy and then create a generate.go file with the following content:

package main

//go:generate go tool ogen --target pkg/o4b --package o4b --clean openapi.yaml

If you now place the omniac Business OpenAPI specification as openapi.yaml in your project root, you can generate the API client with the following command:

go generate

Authentication setup

Now create a main.go file and import the generated code to configure the client. You will need the url as well as your api key. This code needs to be executed before any api call.

package main

import (
	"context"
	omniac "o4b_client_test/pkg/o4b"
)

type APIKeyProvider struct {
	ApiKey string
}

func (a APIKeyProvider) ApiKeyAuth(ctx context.Context, operationName omniac.OperationName) (omniac.ApiKeyAuth, error) {
	return omniac.ApiKeyAuth{APIKey: a.ApiKey}, nil
}

func main() {
	sec := APIKeyProvider{
		ApiKey: "your_api_key_here",
	}
	client, err := omniac.NewClient("https://api.omniac.de", sec)
	if err != nil {
		panic(err)
	}

}

Get tenant info

After initializing the api instance you can use the GetTenant function of your client to get information about your tenant.

[...]

ctx := context.Background()
tenantRes, err := client.GetTenant(ctx)
if err != nil {
    panic(err)
}

switch res := tenantRes.(type) {
case *omniac.Tenant:
    fmt.Println(res)
case *omniac.GetTenantBadRequest:
    fmt.Println("Bad Request:", res)
case *omniac.GetTenantUnauthorized:
    fmt.Println("Unauthorized:", res)
case *omniac.GetTenantInternalServerError:
    fmt.Println("Internal Server Error:", res)
default:
    fmt.Println("Unexpected response type")
}

Add profile to tenant

In order to start the monitoring of attributes and to receive alerts you need to configure a user for your tenant. After successfully creating the profile, you can start adding attributes.

[...]
profileRes, err := client.CreateProfile(ctx, &omniac.ProfileCreateRequest{
    UserLanguage: omniac.NewOptString("de"),
    Name:         "test",
})
if err != nil {
    panic(err)
}

var profile *omniac.Profile
switch res := profileRes.(type) {
case *omniac.Profile:
    profile = res
    fmt.Println(res)
case *omniac.CreateProfileBadRequest:
    fmt.Println("Bad Request:", res)
case *omniac.CreateProfileUnauthorized:
    fmt.Println("Unauthorized:", res)
case *omniac.CreateProfileInternalServerError:
    fmt.Println("Internal Server Error:", res)
default:
    fmt.Println("Unexpected response type")
}

attributeRes, err := client.ReplaceAttributes(ctx, []omniac.AttributeCreateRequest{
    {
        Type: "email",
        Value: "test@example.com",
    }},
    omniac.ReplaceAttributesParams{
        ProfileID: profile.ID,
    })
if err != nil {
    panic(err)
}

switch res := attributeRes.(type) {
case *omniac.ReplaceAttributesOK:
    fmt.Println(res)
case *omniac.ReplaceAttributesBadRequest:
    fmt.Println("Bad Request:", res)
case *omniac.ReplaceAttributesUnauthorized:
    fmt.Println("Unauthorized:", res)
case *omniac.ReplaceAttributesInternalServerError:
    fmt.Println("Internal Server Error:", res)
default:
    fmt.Println("Unexpected response type")
}

Create multiple profiles as a batch

In addition to the option of creating individual profiles, omniac Business also offers the ability to create up to 500 profiles with attributes at the same time.

	batchProfileRes, err := client.CreateProfiles(ctx, []omniac.ProfileCreateBatchRequest{
		{
			UserLanguage: omniac.NewOptString("de"),
			Name:         "batch_test_1",
			Attributes: []omniac.AttributeCreateRequest{
				{
					Type:  "email",
					Value: "test@example.com",
				},
			},
		},
		{
			UserLanguage: omniac.NewOptString("en"),
			Name:         "batch_test_2",
			Attributes: []omniac.AttributeCreateRequest{
				{
					Type:  "email",
					Value: "test2@example.com",
				},
			},
		},
	})

	if err != nil {
		panic(err)
	}

	switch res := batchProfileRes.(type) {
	case *omniac.CreateProfilesCreated:
		fmt.Println(res)
	case *omniac.CreateProfilesBadRequest:
		fmt.Println("Bad Request:", res)
	case *omniac.CreateProfilesUnauthorized:
		fmt.Println("Unauthorized:", res)
	case *omniac.CreateProfilesInternalServerError:
		fmt.Println("Internal Server Error:", res)
	default:
		fmt.Println("Unexpected response type")
	}

Get alerts

After waiting some minutes alerts will appear, if there are any leaks found. You can pull them by using the getprofile function with your profile.id. The two parameters after the profileID let you also return the users attributes (hashed and encrypted) as well as the alerts.

[...]
alertRes, err := client.GetAlerts(ctx, omniac.GetAlertsParams{
    ProfileID: omniac.NewOptString(profile.ID),
})
if err != nil {
    panic(err)
}

switch res := alertRes.(type) {
case *omniac.GetAlertsOK:
    fmt.Println(res.Data)
case *omniac.GetAlertsBadRequest:
    fmt.Println("Bad Request:", res)
case *omniac.GetAlertsUnauthorized:
    fmt.Println("Unauthorized:", res)
case *omniac.GetAlertsInternalServerError:
    fmt.Println("Internal Server Error:", res)
default:
    fmt.Println("Unexpected response type")
}

Provide a push alert endpoint

To get notified even faster, we provide a push api for new alerts. As soon as something is found, we will publish the alert into your system. This is done over a HTTP-call. The delivery will be marked as done on our side as soon as your api returns a 2xx http status code.

To use this feature, you need to contact us, so we can enable the feature for your tenant.

3.2 - Example Python

A example for a python script that enrolls data within our solution

Introduction and project setup

Python is a versatile, high-level programming language praised for its readability and extensive libraries, making it ideal for web development, data analysis, and automation. To manage project-specific dependencies and avoid conflicts, it’s best practice to use a virtual environment. You can create one in your project directory by running the terminal command python -m venv .venv, where .venv is the name of your environment folder. Once created, you must activate it. On Windows, use .venv\Scripts\activate, and on macOS or Linux, use source .venv/bin/activate. After activation, your command prompt will change to show the environment’s name, and any packages you install with pip will be isolated to that specific project. When you’re finished, simply type deactivate to return to your global Python context. This process keeps your projects tidy and reproducible.

Recommendation: codium for development

VSCodium, the open-source build of VS Code, is an excellent choice for Python development. After installing it, the first step is to add the official Python extension from the marketplace, which unlocks powerful features like IntelliSense (code completion), linting (error checking), and debugging. Open your project folder in Codium (File > Open Folder...). The editor will often automatically detect your virtual environment, but you can always manually select it by opening the Command Palette (Ctrl+Shift+P), searching for “Python: Select Interpreter”, and choosing the Python executable located inside your myenv folder. This correctly configures Codium to use your project’s isolated packages. You can then use the integrated terminal (Ctrl+ ) to run your scripts, install new packages with pip`, and manage version control with Git, all without leaving the editor. With the ability to set breakpoints and step through your code using the ‘Run and Debug’ panel, Codium provides a comprehensive and streamlined environment for building and testing your Python tool from start to finish.

Lets go

We highly recommend to use a unix based development environment. This is not only possible by using linux or macOS but also by installing Linux Subsystem for Windows. If you use a plan windows you might need to adapt in certain steps.

Generate venv

As shown above, we will use a venv. To do so we just execute the following commands.

python3 -m venv .venv
source .venv/bin/activate

Generate API code

As recommended in our documentation we use openapi-generator to generate the necessary code to interact with the API. This ensures safety and will break on critical errors as soon as possible.

mkdir api
openapi-generator-cli generate -i openapi.yaml -g python -o /api
cd api
pip install .
touch client.py

With your newly created client.py file you can now import the generated code and configure the client. You need the URL as well as your API-Key. This code has to be executed before issuing any api call.

import openapi_client as omniac

configuration = omniac.Configuration(
    host = "https://api.omniac.de"
)
configuration.api_key["ApiKeyAuth"] = "YOUR_API_KEY_GOES_HERE"

Get tenant info

Now you can initialize a api instance of the TenantAPI. Use the gettenant function of your api_client to get information about your tenant.

import openapi_client as omniac

[...]
with omniac.ApiClient(configuration) as api_client:
    api_instance = omniac.TenantApi(api_client)
	api_instance = omniac.TenantApi(api_client)
    try:
        tenant = api_instance.get_tenant()
        print(tenant)
    except Exception as e:
        print(f"Error: {e}")

Add profile to tenant

In order to start the monitoring of attributes and to receive alerts you need to configure a user for your tenant. After successfully creating the profile, you can start adding attributes.

import openapi_client as omniac

[...]
with omniac.ApiClient(configuration) as api_client:
    api_instance = omniac.ProfileApi(api_client)
    newProfile = omniac.ProfileCreateRequest(
        name="test",
        user_language="de",
    )
    try:
        profile = api_instance.create_profile(newProfile)

		print(profile.id)
        
        api_response = api_instance.replace_attributes(profile.id, [
            omniac.AttributeCreateRequest(
                type="email",
                value="test@example.com"
            )
        ])
        print(api_response)
    except Exception as e:
        print(f"Error: {e}")

Create multiple profiles as a batch

In addition to the option of creating individual profiles, omniac Business also offers the ability to create up to 500 profiles with attributes at the same time.

import openapi_client as omniac

[...]

with omniac.ApiClient(configuration) as api_client:
    api_instance = omniac.ProfileApi(api_client)
    profile_create_batch_request = [omniac.ProfileCreateBatchRequest(
        name="Test1",
            user_language="de",
            attributes=[
                omniac.AttributeCreateRequest(
                    type="email",
                    value="test@example.com"
                )
            ]
    )]
    
try:
    profiles = api_instance.create_profiles(profile_create_batch_request)
    print(profiles)
except Exception as e:
    print(f"Error: {e}")

Get alerts

After waiting some minutes alerts will appear, if there are any leaks found. You can pull them by using the getprofile function with your profile.id. The two parameters after the profileID let you also return the users attributes (hashed and encrypted) as well as the alerts.

import openapi_client as omniac

[...]
with omniac.ApiClient(configuration) as api_client:
    api_instance = omniac.ProfileApi(api_client)
    try:
        profile = api_instance.get_profile("profileID", True, True)
        print(profile)
    except Exception as e:
        print(f"Error: {e}")

Provide a push alert endpoint

To get notified even faster, we provide a push api for new alerts. As soon as something is found, we will publish the alert into your system. This is done over a HTTP-call. The delivery will be marked as done on our side as soon as your api returns a 2xx http status code.

To use this feature, you need to contact us, so we can enable the feature for your tenant.

3.3 - Example Java

A example for a java application that enrolls data within our solution

Introduction and project setup

Java is a robust, object-oriented programming language known for its platform independence and strong type system, making it ideal for enterprise applications, web services, and large-scale systems. To manage project dependencies and build processes effectively, it’s best practice to use a build tool like Maven or Gradle. For this guide, we’ll use Maven. You can create a new Maven project by running mvn archetype:generate -DgroupId=com.example.omniac -DartifactId=omniac-client -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false in your terminal. This creates a standard project structure with a pom.xml file for dependency management. Navigate to your project directory with cd omniac-client. The Maven structure keeps your source code in src/main/java and tests in src/test/java, providing a clean and organized development environment that’s easily understood by IDEs and other developers.

Recommendation: IntelliJ IDEA for development

IntelliJ IDEA is an excellent choice for Java development, offering powerful features out of the box. After installing it, open your Maven project by selecting File > Open and choosing your project’s root directory (where the pom.xml file is located). IntelliJ will automatically detect the Maven project structure and download dependencies. The IDE provides excellent IntelliSense (code completion), built-in refactoring tools, and comprehensive debugging capabilities. You can run your application directly from the IDE using the green play button, or use the integrated terminal (Alt+F12) to execute Maven commands like mvn compile, mvn test, or mvn package. The built-in version control integration makes it easy to manage your Git repository. With features like automatic imports, code formatting, and intelligent error detection, IntelliJ IDEA provides a comprehensive development environment for building and testing your Java application efficiently.

Lets go

We highly recommend to use a unix based development environment. This is not only possible by using linux or macOS but also by installing Linux Subsystem for Windows. If you use a plain windows you might need to adapt in certain steps.

Setup Maven project

As shown above, we will use Maven for dependency management. If you haven’t created the project yet, execute the following commands:

mvn archetype:generate -DgroupId=com.example.omniac -DartifactId=omniac-client -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
cd omniac-client

Generate API code

As recommended in our documentation we use openapi-generator to generate the necessary code to interact with the API. This ensures safety and will break on critical errors as soon as possible.

First, add the OpenAPI Generator Maven plugin to your pom.xml:

<project>
    <!-- ... existing configuration ... -->
    
    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>3.8.1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.6.8</version>
        </dependency>
        <dependency>
            <groupId>com.squareup.okhttp3</groupId>
            <artifactId>okhttp</artifactId>
            <version>4.10.0</version>
        </dependency>
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.10.1</version>
        </dependency>
        <!-- Additional dependencies required by generated code -->
        <dependency>
            <groupId>javax.annotation</groupId>
            <artifactId>javax.annotation-api</artifactId>
            <version>1.3.2</version>
        </dependency>
        <dependency>
            <groupId>com.google.code.findbugs</groupId>
            <artifactId>jsr305</artifactId>
            <version>3.0.2</version>
        </dependency>
        <dependency>
            <groupId>javax.ws.rs</groupId>
            <artifactId>javax.ws.rs-api</artifactId>
            <version>2.1.1</version>
        </dependency>
        <dependency>
            <groupId>com.squareup.okhttp3</groupId>
            <artifactId>logging-interceptor</artifactId>
            <version>4.10.0</version>
        </dependency>
        <dependency>
            <groupId>io.gsonfire</groupId>
            <artifactId>gson-fire</artifactId>
            <version>1.7.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>6.6.0</version>
            <executions>
            <execution>
                <goals>
                <goal>generate</goal>
                </goals>
                <configuration>
                <inputSpec>${project.basedir}/openapi.yaml</inputSpec>
                <generatorName>java</generatorName>
                <output>${project.basedir}/target/generated-sources</output>
                <apiPackage>com.example.omniac.api</apiPackage>
                <modelPackage>com.example.omniac.model</modelPackage>
                <generateSupportingFiles>true</generateSupportingFiles>
                <invokerPackage>com.example.omniac.client</invokerPackage>
                <configOptions>
                    <library>okhttp-gson</library>
                </configOptions>
                </configuration>
            </execution>
            </executions>
        </plugin>
        </plugins>
    </build>
</project>

Then copy your openapi.yaml file to the project root and generate the client:

mvn clean generate-sources

Now create a main class to configure the API client. Create src/main/java/com/example/omniac/OmniacClient.java:

package com.example.omniac;

import com.example.omniac.client.ApiClient;
import com.example.omniac.client.Configuration;

public class OmniacClient {
    private static ApiClient apiClient;
    
    public static void initializeClient(String apiKey) {
        apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.omniac.de");
        apiClient.setApiKey(apiKey);
    }
    
    public static ApiClient getApiClient() {
        return apiClient;
    }
}

Get tenant info

Now you can initialize an API instance of the TenantAPI. Use the getTenant function of your API client to get information about your tenant.

package com.example.omniac;

import com.example.omniac.api.TenantApi;
import com.example.omniac.model.Tenant;

public class TenantExample {
    public static void main(String[] args) {
        // Initialize the client with your API key
        OmniacClient.initializeClient("YOUR_API_KEY_GOES_HERE");
        
        TenantApi tenantApi = new TenantApi(OmniacClient.getApiClient());
        
        try {
            Tenant tenant = tenantApi.getTenant();
            System.out.println(tenant);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Add profile to tenant

In order to start the monitoring of attributes and to receive alerts you need to configure a user for your tenant. After successfully creating the profile, you can start adding attributes.

package com.example.omniac;

import com.example.omniac.api.ProfileApi;
import com.example.omniac.model.Profile;
import com.example.omniac.model.ProfileCreateRequest;
import com.example.omniac.model.AttributeCreateRequest;
import com.example.omniac.model.AttributeType;
import java.util.Arrays;
import java.util.List;

public class ProfileExample {
    public static void main(String[] args) {
        // Initialize the client with your API key
        OmniacClient.initializeClient("YOUR_API_KEY_GOES_HERE");
        
        ProfileApi profileApi = new ProfileApi(OmniacClient.getApiClient());
        
        // Create a new profile
        ProfileCreateRequest newProfile = new ProfileCreateRequest()
            .name("test")
            .userLanguage("de");
        
        try {
            Profile profile = profileApi.createProfile(newProfile);
            System.out.println("Created profile with ID: " + profile.getId());
            
            // Add attributes to the profile
            AttributeCreateRequest emailAttribute = new AttributeCreateRequest()
                .type("email")
                .value("test@example.com");
            
            List<AttributeCreateRequest> attributes = Arrays.asList(emailAttribute);
            
            Object apiResponse = profileApi.replaceAttributes(profile.getId(), attributes);
            System.out.println("Attributes added: " + apiResponse);
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Create multiple profiles as a batch

In addition to the option of creating individual profiles, omniac Business also offers the ability to create up to 500 profiles with attributes at the same time.

package com.example.omniac;

import java.util.ArrayList;
import java.util.List;

import com.example.omniac.api.ProfileApi;
import com.example.omniac.model.AttributeCreateRequest;
import com.example.omniac.model.CreateProfiles201Response;
import com.example.omniac.model.ProfileCreateBatchRequest;

 public static void main(String[] args) {
        // Replace with a real API key or load from environment
        OmniacClient.initializeClient("YOUR_API_KEY_GOES_HERE");

        ProfileApi profileApi = new ProfileApi(OmniacClient.getApiClient());

        List<ProfileCreateBatchRequest> batch = new ArrayList<>();

        ProfileCreateBatchRequest req = new ProfileCreateBatchRequest()
                .name("Test1")
                .userLanguage("de");

        // add attribute
        req.addAttributesItem(new AttributeCreateRequest()
                .type("email")
                .value("test@example.com")
        );

        batch.add(req);

        try {
            CreateProfiles201Response resp = profileApi.createProfiles(batch);
            System.out.println("CreateProfiles response: " + resp);
        } catch (com.example.omniac.client.ApiException e) {
            System.err.println("Error calling createProfiles: " + e.getMessage());
            e.printStackTrace();
        }
    }

Get alerts

After waiting some minutes alerts will appear, if there are any leaks found. You can pull them by using the getProfile function with your profile ID. The two parameters after the profileID let you also return the users attributes (hashed and encrypted) as well as the alerts.

package com.example.omniac;

import com.example.omniac.api.ProfileApi;
import com.example.omniac.model.Profile;

public class AlertsExample {
    public static void main(String[] args) {
        // Initialize the client with your API key
        OmniacClient.initializeClient("YOUR_API_KEY_GOES_HERE");
        
        ProfileApi profileApi = new ProfileApi(OmniacClient.getApiClient());
        
        try {
            // Replace "profileID" with your actual profile ID
            Profile profile = profileApi.getProfile("profileID", true, true);
            System.out.println("Profile with alerts: " + profile);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Provide a push alert endpoint

To get notified even faster, we provide a push API for new alerts. As soon as something is found, we will publish the alert into your system. This is done over an HTTP call. The delivery will be marked as done on our side as soon as your API returns a 2xx HTTP status code.

To use this feature, you need to contact us, so we can enable the feature for your tenant.