Dirs21 API setup guide: enabling and configuring API access

This guide walks through the process of enabling Dirs21 API access for your property account, generating an API key, understanding API permission scopes and connecting CockpitMod add-ons. It assumes you have an active Dirs21 subscription with an account on the dirs21.de platform.

Step 1: Check your subscription tier

API access is available on Dirs21 Professional and Enterprise subscription tiers. If you are on the Basic tier, API access may not be included. Log into your Dirs21 account and navigate to Settings → Subscription to confirm your current tier. If API access is not listed as an included feature, contact dirs21 GmbH to discuss an upgrade.

Step 2: Enable API access

In your Dirs21 account navigate to Settings → Integrations → API Access. If this section is visible and shows a status of "Not enabled", click the Enable API Access button. You will be prompted to accept the Dirs21 API terms of use. Read and accept these terms. API access is typically activated immediately, though in some cases it may take up to 1 hour to propagate across the Dirs21 infrastructure.

Step 3: Generate an API key

With API access enabled, you will see an API key management interface. Click Generate New Key. Give the key a descriptive name — for example "CockpitMod Production" — so you can identify it if you later have multiple keys. The full API key is displayed once at this point. Copy it immediately and store it securely. The key will not be shown in full again; only the first 8 and last 4 characters are displayed thereafter for identification.

Step 4: Configure permission scopes

Dirs21 API keys can be scoped to specific permission levels. For CockpitMod add-ons, configure the following minimum permissions: Reservations Read, Reservations Write, Rates Read, Rates Write (for Corporate Rate Manager only), Guests Read, and Reports Read. If you are uncertain which modules you will purchase, enabling all permissions initially is acceptable — you can restrict scopes later.

Step 5: Locate your property identifier

Your Dirs21 property identifier is required alongside the API key. Navigate to Settings → Hotel Profile to find the Property ID field. This is a numeric or alphanumeric identifier assigned by dirs21 GmbH. Note this value alongside your API key.

Step 6: Connect to CockpitMod

In your CockpitMod account (accessed via the link sent to your registered email after purchase), navigate to Settings → API Configuration. Paste your Dirs21 API key and Property ID into the respective fields. Click Validate & Save. The system makes a test call to the Dirs21 API immediately and confirms that the connection is healthy. If the validation fails, check that the API key is entered in full without extra spaces and that the required permission scopes are enabled.

Troubleshooting

• Error: "Invalid API key" — check that the key is copied in full including any trailing characters
• Error: "Insufficient permissions" — review the permission scopes on the key in your Dirs21 account settings
• Error: "Property not found" — verify the property identifier is correct in your Dirs21 hotel profile
• Error: "Rate limit exceeded" — contact dirs21 GmbH to review your API quota

Security best practices for API keys

Never share your Dirs21 API key by email or chat. Do not paste it into shared documents. Rotate the key every 90 days as a security best practice — remember to update the new key in your CockpitMod account settings immediately after rotation. If you suspect a key has been compromised, delete it in your Dirs21 account settings and generate a new one. The compromised key will stop working immediately.