Managing partner API keys

This instruction describes registration of partners (end users) of an installed On-Premise system and creation of API keys for them. You will learn:

• how to add a partner to the system
• how to create a key for the partner
• how to set up limitations for the key

In the API keys management interface, Partner is a synonym of an end user who interacts with installed services (for example, maps). In the instruction below, only the term partner is used.

Getting started

Before getting started, make sure that the following steps are completed:

1. API Keys service is installed and works properly.
2. User with administrator rights is added to the service using the keysctl utility.

After that:

1. Go to a link of the following format: https://keys.example.com/ (you get it as a result of the service installation).
2. Enter the web interface using the administrator credentials.

In the admin interface you can work with two tabs:

• Partners

  

  Here you can:

  • Add new partners.

  • See the list of existing partners and filter it by required parameters: partner name, key, contact person data, login of a manager (administrator who created a partner), and others.

  • Extract the partner list in the .xlsx format. Click Download partners.xlsx in the upper-right corner of the screen.

    The downloaded file contains all existing partners, applied filters are disregarded.

• API keys

  

  Here you can:

  • See the list of existing keys of all partners and filter it by required parameters: key number, contact person email, login of a manager (administrator who created a partner), and others.

  • Extract the keys list in the .xlsx format. Click Download keys.xlsx in the upper-right corner of the screen.

    The downloaded file contains all existing keys, applied filters are disregarded.

Adding a partner

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

2. Fill in the partner information:

   
   • Name: account name to be displayed in the admin interface.
   • Country: country of partner residence.
   • City: city of partner residence.
   • Language: language of communication with the partner.
   • Contact person: information about the partner contact person: full name and email. By default, this information is used for all partner keys unless alternative data is specified for individual keys.

3. Click Add.

Editing the partner data

1. In the Partners tab, select the required partner.
2. Click the icon next to the partner name.
3. Changed necessary data and click Save.

Creating a key

1. In the Partners tab, select the required partner.

2. Click Create a key.

3. Fill in the information:

   

   • Partner: ID of the partner for which a key is created (by default, the current partner is selected).

   • Mode:

     • Demo: exploratory mode with service limitations (for example, a limited number of requests).

       • Search: not more than 5 pages with results, not more than 20 results per page.
       • Navigation: route length not more than 50 km.

     • Prod: full operation mode.

   • Key purpose: description of the key purpose.

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

4. Click Create.

Note

You can create multiple keys for one partner with different limitations or service lists.

Managing a key

Changing key data

You can change key description and contact person and reassign the key to a different partner as follows:

1. Select the required key in the partner card or in the API keys tab.
2. Click the icon next to the key number.
3. Changed necessary data and click Save.

To change the key mode (Demo/Prod), use the radio buttons on the key main page.

Selecting services

You can change the list of services that the partner can access using the given key:

1. Select the required key in the partner card or in the API keys tab.
2. Scroll down to see the list of available services.
3. To add or remove access to the service, use the switch to the left of the service name.

Deactivating a key

1. Select the required key in the partner card or in the API keys tab.
2. Click Deactivate.

Access to all services in the key is removed, key status is changed to Inactive. To restore the key, click Activate.

Key restrictions

To set up key restrictions:

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

2. Click the icon in the Key restrictions panel.

3. Configure the restrictions:

   

   • Deactivation time: date of the future block (missing by default).

   • By territory:

     • Segment groups: list of accessible segments (territories). By default, a partner can access all segments from the list but you can narrow it.
     • Included segments: additional list of segments outside of the previously selected groups that will be accessible. For example, you can select the whole territory of one country and add a city from another one.
     • Excluded segments: list of segments from the previously selected groups that will not be accessible. For example, you can grant access to the whole territory of the country except one city.

   • By IP or subnets: list of IP addresses that will be restricted for the key usage.

   • By HTTP headers: access restrictions for requests by the server name, page URL, and other parameters.

4. Click Save.

The specified restrictions are applied to all services for the given key.