Authentication

Registration

Access to the API service is protected by our identity provider service.

To register for an account please apply for a trade mark data account.

Note

Currently, even if you plan to use the API service for other data domains than trade mark, please sign up for a trade mark data account. Usage is not restricted to trade mark data.

Access Tokens

To acquire initial access tokens and refresh existing ones, you need to interact with the OpenID Connect token endpoint at the following URL:

https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token

The client_id used for this process is the constant string: datadelivery-api-client.

The successful JSON responses from this token endpoint are structured as follows:

{
  "access_token": "HEADER.PAYLOAD.SIGNATURE",
  "expires_in": 720,
  "refresh_expires_in": 360,
  "refresh_token": "HEADER.PAYLOAD.SIGNATURE",
  "token_type": "bearer",
  "not-before-policy": 1559831758,
  "session_state": "UUID",
  "scope": ""
}

• Status 200: Successful Response

• Status 4xx: Error Response

This JSON response includes properties such as the access_token, which is used for authentication, and refresh_token, which allows you to obtain a new access token without re-authenticating. The expires_in and refresh_expires_in fields indicate the validity duration (seconds) of the access and refresh tokens, respectively.

Get initial tokens

You can acquire the initial pair of access and refresh tokens by utilizing the OAuth 2.0: Resource Owner Password Credentials Grant procedure.

Important

Do not get new initial tokens for every API request. Instead, reuse the access_token throughout its validity period as specified by the expires_in property in the token endpoint response. To extend the token’s validity, use the refresh_token rather than repeatedly requesting new initial tokens. Failing to reuse tokens appropriately may result in penalties.

Refresh the tokens

Before the refresh_token expires, employ the OAuth 2.0: Refreshing an Access Token procedure to obtain a new pair of access and refresh tokens.

Important

The total lifetime of a session is limited to 600 minutes (10 hours). If, after refreshing, the expires_in value of the new access_token is less than the normal 720 seconds, then start a new session by getting a fresh initial token.

Examples

VS Code REST Client

REST Client: ipi_datadelivery.http

###
# @name login
# @prompt username IDP_USERNAME (email)
# @prompt password IDP_PASSWORD
POST https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=datadelivery-api-client
&grant_type=password
&username={{username}}
&password={{password}}

###
@base_url = https://www.swissreg.ch/public
@access_token = {{login.response.body.$.access_token}}
@expires_in = {{login.response.body.$.expires_in}}
@refresh_token = {{login.response.body.$.refresh_token}}
@refresh_expires_in = {{login.response.body.$.refresh_expires_in}}

###
# @name login
POST https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=datadelivery-api-client
&grant_type=refresh_token
&refresh_token={{refresh_token}}

###
POST {{base_url}}/api/v1
Authorization: Bearer {{access_token}}
Accept: application/xml
Content-Type: application/xml

<ApiRequest xmlns="urn:ige:schema:xsd:datadeliverycore-1.0.0" uuid="{{$guid}}" timestamp="{{$datetime iso8601}}">
</ApiRequest>

###
POST {{base_url}}/api/v1
Authorization: Bearer {{access_token}}
Accept: application/xml
Content-Type: application/xml

<ApiRequest xmlns="urn:ige:schema:xsd:datadeliverycore-1.0.0" uuid="{{$guid}}" timestamp="{{$datetime iso8601}}">
    <Action type="Echo"/>
    <Action type="UserQuota"/>
</ApiRequest>

Bash shell

# IDP credentials
IDP_USERNAME="${IDP_USERNAME-"$(read -r -p    'IDP_USERNAME: '; echo "${REPLY}")"}" #e.g. "hanna.muster@example.com"
IDP_PASSWORD="${IDP_PASSWORD-"$(read -r -s -p 'IDP_PASSWORD: '; echo "${REPLY}")"}" #e.g. "s3cretPassWord"

# API smoketest
function api_smoketest() {
  API_ENDPOINT="https://www.swissreg.ch/public/api/v1"
  NO_ACTION_REQUEST="<ApiRequest xmlns='urn:ige:schema:xsd:datadeliverycore-1.0.0'/>"
  curl -D /dev/stderr -X POST -H "$API_AUTHORIZATION" -H 'Accept: application/xml' -H 'Content-Type: application/xml' --data-binary "${NO_ACTION_REQUEST}" "${API_ENDPOINT}"

  command -v oha >/dev/null && # https://github.com/hatoo/oha
  oha -c 12 -n 100 -m POST -H "$API_AUTHORIZATION" -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d "${NO_ACTION_REQUEST}" "${API_ENDPOINT}"
}

# Get initial tokens
IDP_RESPONSE="$(curl -s -D /dev/stderr \
  -H "accept: application/json" \
  -d "grant_type=password" \
  -d "client_id=datadelivery-api-client" \
  -d "username=${IDP_USERNAME}" \
  -d "password=${IDP_PASSWORD}" \
  "https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token"
)"

## Extract tokens from response
jq '. | .expires_in, .refresh_expires_in' <<<"$IDP_RESPONSE"
IDP_TOKEN="$(jq -r .access_token <<<"$IDP_RESPONSE")"
IDP_REFRESH_TOKEN="$(jq -r .refresh_token <<<"$IDP_RESPONSE")"
API_AUTHORIZATION="Authorization: Bearer ${IDP_TOKEN}"

api_smoketest

# Refresh the tokens
IDP_RESPONSE="$(curl -s -D /dev/stderr \
  -H "accept: application/json" \
  -d "grant_type=refresh_token" \
  -d "client_id=datadelivery-api-client" \
  -d "refresh_token=${IDP_REFRESH_TOKEN}" \
  "https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token"
)"

## Extract tokens from response
jq '. | .expires_in, .refresh_expires_in' <<<"$IDP_RESPONSE"
IDP_TOKEN="$(jq -r .access_token <<<"$IDP_RESPONSE")"
IDP_REFRESH_TOKEN="$(jq -r .refresh_token <<<"$IDP_RESPONSE")"
API_AUTHORIZATION="Authorization: Bearer ${IDP_TOKEN}"

api_smoketest

export API_AUTHORIZATION

TypeScript with Deno

TypeScript: ipi_datadelivery.ts

import { delay } from "jsr:@std/async/delay";
import { promptSecret } from "jsr:@std/cli/prompt-secret";

const idpClientId = "datadelivery-api-client";
const idpEndpoint =
  "https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token";

const apiEndpoint = "https://www.swissreg.ch/public/api/v1";
const noActionRequest =
  `<ApiRequest xmlns='urn:ige:schema:xsd:datadeliverycore-1.0.0'/>`;

// Utility function to prompt user for input.
function getConfig(envVar: string, hide: boolean): string {
  const envValue = Deno.env.get(envVar);
  if (envValue) {
    return envValue;
  }
  const input = (hide ? promptSecret : prompt)(`${envVar}: `);
  if (!input) {
    throw new Error(`No input provided for ${envVar}`);
  }
  return input;
}

const idpUsername = getConfig("IDP_USERNAME", false);
const idpPassword = getConfig("IDP_PASSWORD", true);

// Global token storage.
// deno-lint-ignore no-explicit-any
let tokenData: Record<string, any> = {};

// Fetches a token from the IDP using the specified grant type and parameters.
async function fetchToken(
  grantType: string,
  params: Record<string, string>,
): Promise<Record<string, unknown>> {
  console.log(`Requesting token with grant_type: ${grantType}...`);

  const formData = new URLSearchParams({
    grant_type: grantType,
    client_id: idpClientId,
    ...params,
  });

  const response = await fetch(idpEndpoint, {
    method: "POST",
    headers: {
      "Accept": "application/json",
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: formData.toString(),
  });

  if (!response.ok) {
    throw new Error(
      `Error fetching token: ${response.status} ${response.statusText}`,
    );
  }
  const data = await response.json();

  console.log(
    "Token expires_in:",
    data.expires_in,
    ", refresh_expires_in:",
    data.refresh_expires_in,
  );

  return data;
}

// Get credentials and request the initial token.
async function initialToken(): Promise<void> {
  console.log("Initial token...");
  tokenData = await fetchToken("password", {
    username: idpUsername,
    password: idpPassword,
  });
}

// Refreshes token and updates tokenData.
async function refreshToken(): Promise<void> {
  console.log("Refreshing token...");
  if (!tokenData.refresh_token) {
    throw new Error("No refresh token available");
  }
  tokenData = await fetchToken("refresh_token", {
    refresh_token: tokenData["refresh_token"],
  });
  console.log("Token refreshed. New access token:", tokenData.access_token);
}

// Starts a background loop that periodically refreshes the token.
export async function startTokenRefreshLoop(): Promise<void> {
  await initialToken();
  (async function refreshLoop() {
    while (true) {
      const refreshExpiresIn = tokenData.refresh_expires_in;
      // Calculate sleep time as 90% of the current refresh token's lifetime (in seconds)
      const sleepSeconds = Math.max(1, Math.floor(refreshExpiresIn * 0.9));
      console.log(
        `Sleeping for ${sleepSeconds} seconds before next token refresh...`,
      );
      await delay(sleepSeconds * 1000);

      const oldExpires = tokenData.expires_in;
      try {
        await refreshToken();
      } catch (e) {
        console.error(
          "Error in refresh-token:",
          (e as Error).message,
          "- calling initial-token instead.",
        );
        await initialToken();
      }
      // If new "expires_in" is lower than the previous value then reinitialize token.
      if (tokenData.expires_in < oldExpires) {
        console.log(
          "New :expires_in is lower than the previous value; fetching new initial token...",
        );
        await initialToken();
      }
    }
  })();
}

// Sends an authenticated POST request to the API endpoint with the given XML body.
export function apiPost(body: string): Promise<Response> {
  if (!tokenData.access_token) {
    throw new Error("No access token available");
  }
  const headers = {
    "Authorization": `Bearer ${tokenData.access_token}`,
    "Accept": "application/xml",
    "Content-Type": "application/xml",
  };

  return fetch(apiEndpoint, {
    method: "POST",
    headers,
    body,
  });
}

// Runs an API smoketest by sending a no-action XML request to the API.
export async function apiSmokeTest(): Promise<void> {
  console.log("Running API smoketest...");
  try {
    const response = await apiPost(noActionRequest);
    const status = response.status;
    const responseText = await response.text();
    console.log("status =", status, "body =", responseText);
  } catch (e) {
    console.error("Error in API smoketest:", (e as Error).message);
  }
}

if (import.meta.main) {
  await startTokenRefreshLoop();
  await delay(1000);
  console.log("Press Ctrl+C to exit.");
  while (true) {
    await apiSmokeTest();
    await delay(300_000);
  }
}

Clojure with Babashka

Babashka: ipi_datadelivery.bb

#!/usr/bin/env bb
(ns ipi-datadelivery
  (:require [babashka.http-client :as http]
            [clojure.data.xml :as xml]
            [cheshire.core :as json]))

(def api-endpoint "https://www.swissreg.ch/public/api/v1")
(def idp-endpoint "https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token")
(def idp-client-id "datadelivery-api-client")

(defn- get-config
  [env-var hide?]
  (or (System/getenv env-var)
      (let [prompt-msg (str env-var ": ")]
        (if hide?
          (println prompt-msg "(input will be visible)")
          (print prompt-msg))
        (flush)
        (read-line))))

(def idp-username (get-config "IDP_USERNAME" false))
(def idp-password (get-config "IDP_PASSWORD" true))

;; Global atom to store token information.
(def ^:private token-data (atom {}))

(defn- fetch-token
  "Fetches a token from the IDP using the specified grant type and parameters.
   Returns the parsed JSON response."
  [grant-type params]
  (println (str "Requesting token with grant_type: " grant-type "..."))
  (let [resp (http/post idp-endpoint
                        {:headers {"accept" "application/json"}
                         :form-params (merge {"grant_type" grant-type
                                              "client_id" idp-client-id}
                                       params)})
        data (-> resp :body (json/parse-string true))]
    #_(println (:body resp))
    (println "Token expires_in:" (:expires_in data)
             ", refresh_expires_in:" (:refresh_expires_in data))
    data))

(defn- initial-token
  "Obtains the initial token using the user credentials and stores it in token-data."
  []
  (println "Initial token...")
  (let [data (fetch-token "password" {"username" idp-username "password" idp-password})]
    (reset! token-data data)))

(defn- refresh-token
  "Attempts to refresh the token. On success, updates token-data."
  []
  (println "Refreshing token...")
  (let [data (fetch-token "refresh_token" {"refresh_token" (:refresh_token @token-data)})]
    (reset! token-data data)
    (println "Token refreshed. New access token:" (:access_token data))))

(defn start-token-refresh-loop
  "Starts a background loop that periodically refreshes the token.
   It calculates the sleep interval as 90% of the current refresh token's lifetime."
  []
  (initial-token)
  (future
    (while true
      (let [refresh-expires-in (:refresh_expires_in @token-data)
            sleep-seconds (max 1 (int (* refresh-expires-in 0.9)))]
        (println "Sleeping for" sleep-seconds "seconds before next token refresh...")
        (-> sleep-seconds java.time.Duration/ofSeconds Thread/sleep)
        (let [old-expires (:expires_in @token-data)]
          (try
            (refresh-token)
            (catch Exception e
              (println "Error in refresh-token:" (.getMessage e) "- calling initial-token instead.")
              (initial-token)))
          (when (< (:expires_in @token-data) old-expires)
            (println "New :expires_in is lower than the previous value; fetching new initial token...")
            (initial-token)))))))

(defn api-post
  "Sends an authenticated POST request to the API endpoint with the given XML body."
  [body]
  (let [headers {"Authorization" (str "Bearer " (:access_token @token-data))
                 "Accept" "application/xml"
                 "Content-Type" "application/xml"}]
    (http/post api-endpoint {:headers headers :body body})))

(start-token-refresh-loop)
(-> "PT1S" java.time.Duration/parse Thread/sleep)

(defn api-smoketest
  "Runs an API smoketest by sending a no-action XML request to the API.
   It prints the response status, a UUID from the XML response, and the formatted XML."
  []
  (println "Running API smoketest...")
  (let [no-action-request "<ApiRequest xmlns='urn:ige:schema:xsd:datadeliverycore-1.0.0'/>"
        resp (api-post no-action-request)
        xml-data (-> resp :body xml/parse-str)]
    (println "status=" (:status resp)
             "uuid=" (-> xml-data :attrs :uuid)
             "body=" (xml/indent-str xml-data))))

(println "Press Ctrl+C to exit.")
(while true
  (api-smoketest)
  (-> "PT5M" java.time.Duration/parse Thread/sleep))

Python with Requests

Python: ipi_datadelivery.py

#!/usr/bin/env python3
import os
import threading
import time
import xml.etree.ElementTree as ET
from getpass import getpass
import requests
from requests.adapters import HTTPAdapter
from typing import Any, Dict

api_endpoint: str = "https://www.swissreg.ch/public/api/v1"
idp_endpoint: str = "https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token"
idp_client_id: str = "datadelivery-api-client"

api_session: requests.Session = requests.Session()
api_session.mount("https://", HTTPAdapter(pool_connections=12, pool_maxsize=12, max_retries=0, pool_block=True))

def get_config(env_var: str, hide: bool) -> str:
    value: str | None = os.getenv(env_var)
    if value is None:
        prompt: str = f"{env_var}: "
        value = (getpass if hide else input)(prompt)
    return value

idp_username: str = get_config("IDP_USERNAME", False)
idp_password: str = get_config("IDP_PASSWORD", True)

token_data: Dict[str, Any] = {}
token_lock = threading.Lock()

def fetch_token(grant_type: str, params: Dict[str, str]) -> Dict[str, Any]:
    print(f"Requesting token with grant_type: {grant_type}...")
    payload = {"grant_type": grant_type, "client_id": idp_client_id, **params}
    resp = api_session.post(idp_endpoint, headers={"accept": "application/json"}, data=payload)
    data: Dict[str, Any] = resp.json()
    print(f"Token expires_in: {data.get('expires_in')}, refresh_expires_in: {data.get('refresh_expires_in')}")
    return data

def initial_token() -> None:
    print("Initial token...")
    new_token = fetch_token("password", {"username": idp_username, "password": idp_password})
    with token_lock:
        global token_data
        token_data = new_token

def refresh_token() -> None:
    print("Refreshing token...")
    with token_lock:
        current_refresh = token_data.get("refresh_token", "")
        new_data = fetch_token("refresh_token", {"refresh_token": current_refresh})
        token_data.update(new_data)
        print("Token refreshed.")

def token_refresh_loop() -> None:
    initial_token()
    while True:
        with token_lock:
            refresh_expires_in = int(token_data.get("refresh_expires_in", 300))
            old_expires = int(token_data.get("expires_in", 0))
        sleep_seconds: int = max(1, int(refresh_expires_in * 0.9))
        print("Sleeping for", sleep_seconds, "seconds before next token refresh...")
        time.sleep(sleep_seconds)
        try:
            refresh_token()
        except Exception as e:
            print("Error in refresh-token:", str(e), "- calling initial token instead.")
            initial_token()
        with token_lock:
            new_expires = int(token_data.get("expires_in", 0))
        if new_expires < old_expires:
            print("New expires_in is lower than previous; fetching new initial token...")
            initial_token()

def start_token_refresh_loop() -> None:
    threading.Thread(target=token_refresh_loop, daemon=True).start()

def api_post(body: str) -> requests.Response:
    with token_lock:
        access_token = token_data.get("access_token", "")
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Accept": "application/xml",
        "Content-Type": "application/xml"
    }
    return api_session.post(api_endpoint, headers=headers, data=body)

def api_smoketest() -> None:
    print("Running API smoketest...")
    no_action_request: str = "<ApiRequest xmlns='urn:ige:schema:xsd:datadeliverycore-1.0.0'/>"
    resp: requests.Response = api_post(no_action_request)
    try:
        xml_data = ET.fromstring(resp.text)
        uuid = xml_data.attrib.get("uuid", "")
        print(f"status={resp.status_code}, uuid={uuid}, body={ET.tostring(xml_data, encoding='unicode')}")
    except ET.ParseError as e:
        print("XML parse error:", str(e), "body:", resp.text)

start_token_refresh_loop()
time.sleep(2)

print("Press Ctrl+C to exit.")
while True:
    api_smoketest()
    time.sleep(5 * 60)

PowerShell

PowerShell: Get-IpiDataDeliveryToken

function Get-IpiDataDeliveryToken
{
  param (
    [string] $IdpUsername = $env:IDP_USERNAME,
    [string] $IdpPassword = $env:IDP_PASSWORD
  )
    
  $TOKEN_ENDPOINT="https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token"
  $PARAMS = @{
    grant_type = "password"
    client_id = "datadelivery-api-client"
    username = $IdpUsername
    password = $IdpPassword
  }
  $res = Invoke-RestMethod -Method Post -Uri $TOKEN_ENDPOINT -ContentType "application/x-www-form-urlencoded" -Body $PARAMS
  return $res.access_token
}

$IdpCredentials = if ($IdpCredentials) { $IdpCredentials } else {
   Get-Credential -Message "Datadelivery IDP Credentials"
}
$env:IDP_USERNAME = $IdpCredentials.UserName
$env:IDP_PASSWORD = $IdpCredentials.GetNetworkCredential().Password
$env:IDP_TOKEN = $(Get-IpiDataDeliveryToken)

If your account has multi-factor authentication enabled, the 6-digit time-based one-time password (TOTP) must be provided as well.

PowerShell: Get-IpiDataDeliveryTokenWithTotp

function Get-IpiDataDeliveryTokenWithTotp
{
  param (
    [string] $IdpUsername = $env:IDP_USERNAME,
    [string] $IdpPassword = $env:IDP_PASSWORD,
    [string] $IdpTotpToken = $env:IDP_TOTP_TOKEN,
    [string] $IdpTotpSecretBase32 = $env:IDP_TOTP_SECRET_BASE32
  )
    
  $TOKEN_ENDPOINT="https://idp.ipi.ch/auth/realms/egov/protocol/openid-connect/token"
  $PARAMS = @{
    grant_type = "password"
    client_id = "datadelivery-api-client"
    username = $IdpUsername
    password = $IdpPassword
  }
  if ($IdpTotpSecretBase32) {
    function Get-TOTP {
      param (
          [string] $SecretBase32,
          [int] $TimeStepSeconds = 30,
          [int] $OTPCodeLength = 6
      )
    
      function Decode-Base32($base32Input) {
          $num = [Numerics.BigInteger]::Zero
          foreach ($char in ($base32Input.ToUpper() -replace '[^A-Z2-7]').GetEnumerator()) {
              $num = ($num -shl 5) -bor ('ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'.IndexOf($char))
          }
          [byte[]]$decoded = $num.ToByteArray()
          if ($decoded[-1] -eq 0) {
              $decoded = $decoded[0..($decoded.Count - 2)]
          }
          [array]::Reverse($decoded)
          return $decoded
      }
      
      $epochTime = (Get-Date).ToUniversalTime() - ([DateTime]'1970-01-01 00:00:00')
      $seconds = [math]::Floor($epochTime.TotalSeconds)
      $counter = [math]::Floor($seconds / $TimeStepSeconds)
      
      $counterBytes = [byte[]]::new(8)
      $cursor = 7
      while (($counter -gt 0) -and ($cursor -ge 0)) {
          $counterBytes[$cursor] = ($counter -band 0xFF)
          $counter = [math]::Floor($counter / (1 -shl 8))
          $cursor -= 1
      }

      $hmac = New-Object -TypeName System.Security.Cryptography.HMACSHA1
      $hmac.Key = Decode-Base32 $SecretBase32
      $hash = $hmac.ComputeHash($counterBytes)
    
      $offset = $hash[19] -band 0xF
      $fullOTP = ($hash[$offset] -band 0x7F) * (1 -shl 24)
      $fullOTP += ($hash[$offset + 1] -band 0xFF) * (1 -shl 16)
      $fullOTP += ($hash[$offset + 2] -band 0xFF) * (1 -shl 8)
      $fullOTP += ($hash[$offset + 3] -band 0xFF)
      $modNumber = [math]::Pow(10, $OTPCodeLength)
      $otp = $fullOTP % $modNumber

      return $otp.ToString("0" * $OTPCodeLength) 
    }

    $PARAMS += @{
      totp = $(Get-TOTP -SecretBase32 $IdpTotpSecretBase32)
    }
  }
  if ($IdpTotpToken) {
    $PARAMS += @{
      totp = $IdpTotpToken
    }
  }
  $res = Invoke-RestMethod -Method Post -Uri $TOKEN_ENDPOINT -ContentType "application/x-www-form-urlencoded" -Body $PARAMS
  return $res.access_token
}

$IdpCredentials = if ($IdpCredentials) { $IdpCredentials } else {
   Get-Credential -Message "Datadelivery IDP Credentials"
}
$env:IDP_USERNAME = $IdpCredentials.UserName
$env:IDP_PASSWORD = $IdpCredentials.GetNetworkCredential().Password
$env:IDP_TOTP_SECRET_BASE32 = 'NZEX MODQ JZBG UUSS MFKT I33U OJUV C3BW'
$env:IDP_TOKEN = $(Get-IpiDataDeliveryTokenWithTotp)