Managing partner API keys

In the API keys management web interface, a Partner is an end user who interacts with services installed inside the On-Premise system (e.g., maps API).

As an administrator, you can:

• add partners to the system and edit their data
• create API keys for partners and edit API key data
• edit a list of services for the API key that are available to the partner
• deactivate and activate the API key to manage access to services
• add API key restrictions

Getting started

To start using the API keys management web interface, follow the steps below:

1. Make sure that the API Keys service is installed, works properly, and an administrator is added to the service using the keysctl utility. For details, see the Installing API Keys service instruction.
2. Go to a link in the https://keys-admin.example.com/ format that you received after installing the API Keys service.
3. Log in to the web interface using the administrator credentials.

The administrator interface contains two tabs:

• Partners

  

  Here you can:

  • Add new partners.
  • View and filter the list of partners by name, key, contact person data, manager login (an administrator who added the partner), and other parameters.
  • Export the list of all partners in .xlsx format by clicking Download partners.xlsx in the upper-right corner of the interface. The downloaded file contains all existing partners, and filters are not applied.

• API keys

  

  Here you can:

  • View and filter the list of keys for all partners by key number, contact person email, manager login (an administrator who added the partner), and other parameters.
  • Export the list of all keys in .xlsx format by clicking Download keys.xlsx in the upper-right corner of the interface. The downloaded file contains all existing keys, and filters are not applied.

Adding a partner

1. Go to the Partners tab and click Add partner.

2. Fill in the partner information:

   
   • Name: account name displayed in the administrator interface.
   • Country: country of partner residence.
   • City: city of partner residence.
   • Language (optional parameter): language for communication with the partner.
   • Contact person: information about the partner contact person: full name and email. By default, the information is used for all partner keys unless alternative data is specified during API key creation.

3. Click Add.

Editing partner data

1. Go to the Partners tab and select the card of the required partner.
2. Click icon next to the partner name.
3. Apply necessary changes and click Save.

Creating an API key

For each partner, you can create multiple keys with different restrictions and services.

1. Go to the Partners tab and select the card of the required partner.

2. Click Create a key.

3. Fill in the key information:

   

   • Partner: partner for whom the key is created (by default, the current partner is selected).

   • Mode:

     • Demo: trial mode with service limitations:

       • Search APIs: no more than 5 pages of results and no more than 20 results per page.
       • Navigation APIs: route length no more than 50 km.

     • Prod: full operation mode.

   • Key purpose: description of the key purpose.

   • Contact person (optional parameter): information about the contact person for the key. If left empty, the partner contact data is used.

4. Click Create.

Editing API key data

1. Select the required key on the API keys tab or in the partner card on the Partners tab.
2. To edit the key description, the contact person, or assign the key to a different partner, click icon next to the key ID. Apply necessary changes and click Save.
3. To change the key operating mode (Demo/Prod), select it in the Mode block.

Editing a list of services

You can edit a list of services that the partner can access using the key.

1. Select the required key on the API keys tab or in the partner card on the Partners tab.
2. Scroll down the key page to see the list of available services.
3. To grant or revoke access to the service, use the toggle next to the service name.

Deactivating an API key

Deactivating a key blocks access to all its services and changes status to Inactive.

1. Select the required key on the API keys tab or in the partner card on the Partners tab.
2. Click Deactivate next to the key ID.
3. To unblock the key, click Activate.

Adding API key restrictions

Important

Restrictions are applied to all services specified for the API key.

1. Select the required key on the API keys tab or in the partner card on the Partners tab.

2. In the Key restrictions section, click icon.

3. Configure the key restrictions:

   

   • Deactivation time: key deactivation date.

   • By territory: access restriction by territory.

     • Segment groups: list of available geographical segments (territories).
     • Included segments: additional list of available segments outside the selected groups.
     • Excluded segments: list of segments from the selected groups that are not accessible.

   • By application: access restriction by mobile application ID.

   • By IP or subnets: access restriction by IP addresses.

   • By HTTP headers: access restriction by header values.

4. Click Save.

Deactivation time

Allows you to set the date and time for key deactivation, after which the key becomes inactive, and all requests using the key are rejected.

Usage example: set the key validity period until December 31, 2025.

Steps:

1. In the Deactivation time field, enter the date 31.12.2025. The time 12:00:00 in the GMT (UTC+3) timezone is set automatically.
2. Click Save.

Result: the key is active only until 31.12.2025 12:00:00 GMT.

By territory (Segment groups)

Allows access to groups of geographic segments (territories). The key will work only for segments from the specified groups (e.g., UAE), including all regions and cities within those groups.

Usage example: allow access only for users from the UAE.

Steps:

1. In the Segment groups field, select UAE from the dropdown list.
2. Click Save.

Result: the key works for all segments in the United Arab Emirates. Requests from other countries (e.g., Saudi Arabia) are rejected.

By territory (Included segments)

Allows access to segments that are not part of the selected groups, or if no groups are specified. For example, you can select one country as a group and additionally include a segment with one city from another country. Segments already included in the selected groups cannot be added.

Usage example: allow access only for requests from Dubai.

Steps:

1. Leave the Segment groups field empty.
2. In the Included segments field, select Dubai.
3. Click Save.

Result: the key works only for requests from Dubai. Requests from other segments (e.g., Abu Dhabi) are rejected.

By territory (Excluded segments)

Restricts access to segments within the selected groups. For example, you can select the entire territory of the country and restrict access to a specific segment within it.

Usage example: allow access for requests across all the UAE except Dubai.

Steps:

1. In the Segment groups field, select UAE.
2. In the Excluded segments field, select Dubai.
3. Click Save.

Result: the key works for requests from all segments in the UAE except Dubai. For example, requests from Abu Dhabi are allowed.

By application

Restricts access based on the mobile application identifier (appId).

Usage example: allow access only for requests from the application with the identifier com.dgis.sdk.app.

Steps:

1. In the App ID field, enter com.dgis.sdk.app.
2. Click Save.

Result: the key works only for requests from the application with the identifier com.dgis.sdk.app. Requests from other applications (e.g., com.dgis.test.app) are rejected.

By IP or subnets

Restricts access based on a list of IP addresses or subnets in CIDR format (e.g., 192.168.1.0/24). The restriction uses the client IP address extracted from the following headers:

• Remote-Addr: IP address of the TCP connection source or the proxy server IP address when using a proxy or NAT.
• X-Forwarded-For: chain of IP addresses, where the first address is the client IP. It is recommended to use this header, as it supports complex network configurations with proxy.
• X-Real-IP: client IP address passed by the proxy.

Usage example: allow access only for requests from the corporate subnet 192.168.1.0/24.

Steps:

1. In the CIDR field, enter the subnet 192.168.1.0/24.

2. Click Save.

3. If you use a proxy or NAT, headers may be missing or contain incorrect client IP addresses, which can disrupt the restriction. Make sure that your infrastructure (proxy, load balancers, NAT, Ingress) passes headers with the original client IP address:

   • Check the configuration of the Nginx Ingress controller in your Kubernetes cluster (e.g., the values.yaml file in the Helm chart).
   • Check the configuration of the proxy or the load balancer (e.g., the proxy_set_header directive in Nginx).
   • Enable logging of HTTP headers (Remote-Addr, X-Forwarded-For, X-Real-IP) in the API Keys service.
   • Use traffic analysis tools to confirm that at least one header contains the correct client IP address (e.g., Wireshark, tcpdump).

Result: the key works only for requests from IP addresses in the range 192.168.1.0 — 192.168.1.255, provided that one of the headers (Remote-Addr, X-Forwarded-For, X-Real-IP) correctly passes the client IP address. Requests from other IP addresses (e.g., 10.0.0.1) or without valid headers are rejected.

If necessary, you can contact the technical support for configuration clarification or recommendations.

By HTTP headers

Restricts access based on HTTP headers in the request:

• Origin: by server name.
• Referer: by page URL.
• User-Agent: by application type, operating system, and other parameters.

Usage example: allow access only for requests from the domain example.com and from a browser with User-Agent Mozilla/5.0 setting.

Steps:

1. In the Origin field, enter example.com.
2. In the User-Agent field, enter Mozilla/5.0.
3. Click Save.

Result: the key works only for requests with the headers Origin: example.com and User-Agent: Mozilla/5.0. Requests from other domains (e.g., test.com) or other clients (e.g., curl/7.0) are rejected.