API Keys

How to manage your API Keys and restrict them to ensure your Woosmap Platform account is secure.

  1. Overview
  2. Registering a Woosmap Public API Key
  3. Why should I restrict my Public API keys?
  4. What is a Woosmap Public API Key restriction?
  5. Registering a Woosmap Private API key
  6. Why should I restrict my Private API keys?
  7. What is a Woosmap Private API Key restriction?
  8. Restrictions errors
  9. Best practices

Overview

Woosmap Platform APIs and SDKs require you to send an API key with all calls. API keys act as unique identifiers that authenticate the calls you make to Woosmap Platform and ensure they are billed to the correct project and organisation. Whether you’re pushing new or updating existing data, searching it, or doing anything else with Woosmap’s API, you need to provide an API key.

There are two kinds of API Keys: Public and Private.

Public API keys are used to implement Woosmap features on the client-side. They allow you to retrieve your location data and benefit from the read-only capabilities of Woosmap APIs. A unique Public API Key is automatically generated when you add a new project to your organization. Be careful, you must authorize domains or IP addresses to consume API calls to your Public API key.

Private API keys allow you to manage integrations on the server-side or in mobile environments. Those keys can either be used to perform creation of new and updates of existing locations or to request Woosmap APIs from backend or mobile integrations. You need to create Private API keys manually.

Registering a Woosmap Public API Key

Assuming you have already created your Woosmap account.

Steps:

  1. Visit the Woosmap Console and authenticate yourself.

  2. Click on the Projects icon on your left.

  3. Either create a new project or select an existing one.

  4. The Woosmap Public API Key is automatically created. You can see it from the Security tab of your project under the Project API key(s) section.

This Key is a long string of generated characters preceded by woos-.

        woos-26b90591-6d9e-3b74-ba24-a887ec084e86

    

Why should I restrict my Public API keys?

Restricting your Public API keys helps ensure your Woosmap Platform account is secured. To create a new Woosmap Project, you need to set at least one restriction to the Woosmap Public API Key. You can always change the restrictions later, if you need to.

What is a Woosmap Public API Key restriction?

Woosmap Public API Key restrictions are the authorized domains or IPs from which the call to Woosmap API will be done. You can add or remove an authorized domain name in the project creation stage and from the Security tab under the Domain(s) section by clicking on the Manage domains link.
Wildcard characters are acceptable for naming similar websites. For example, *.woosmap.com accepts all sites ending with .woosmap.com, such as https://developers.woosmap.com.

No need to specify the path of your url page like www.mybrand.com/mypage/. Just specify the domain name www.mybrand.com. Also, do not insert the protocol (http/https) in front of your domain name as it is not supported.

Add or remove an authorized domain name

Registering a Woosmap Private API key

Assuming you have already created your Woosmap account.

Steps:

  1. Visit the Woosmap Console and authenticate yourself.

  2. Click on the Projects icon on your left.

  3. Either create a new project or select an existing one.

  4. From the Security tab, click on the Add a Private Key link.

  5. Specify a Name. According to the API Key destination (request or data management) check the “Give the private key write the permission (creation and edition)”. Warning: permissions cannot be changed after the private key has been created.

  6. Choose the proper restriction you want to apply to your API key. Fill in the expected informations.
    • No restriction = usable key but unsecured. May put your project at risk if the API key is shared.
    • iOS = dedicated to mobile use on iOS environment
    • Android = dedicated to mobile use on Android environment
    • IP = dedicated to backend side integration to restrict request to a list of authorised IPs. A private key can only bears one type of restriction at a time.
  7. Once restrictions applied, click on the button Add

Private API Key creation

Keys are long strings of generated characters.

        b887ecb5-e0bb-4b7b-a554-54e4a3d96e7a

    

Why should I restrict my Private API keys?

Restricting your Private API keys helps ensure your Woosmap Platform account is secured. If you want to use Woosmap API server side or in mobile application, you need to restrict your Private Keys. As for authorised domains for Public Keys, restrictions can be changed later if you need to.

What is a Woosmap Private API Key restriction?

Woosmap Private API Key restrictions depends on where those keys will be used. Properly set, they’ll authorized mobile applications or IPs to request Woosmap APIs. Private keys and restrictions can only be added to an existing project in our console. Please use the Security tab and the Add a private key button to do so.

A No restriction status is available. Use it at your own risk. Not securing your API keys may lead to unwanted usage.

According to the restriction you want to set, different information must be provided:

e.g. restriction setting for iOS Add restriction for iOS integration

e.g restriction setting for server side use Add restriction for IP

To find out the values you’ll need for mobile restrictions:

We strongly recommand to use our mobile SDKs when using our APIs from a mobile application. They will automatically resolve and set everything for you when emitting a request to our services. However, if you still want to handle the requests code yourself, you will need to pass additional HTTP headers:

Restrictions errors

If requests to Woosmap API are done with wrong API keys or without fulfilling the required restrictions you may encounter 401 unauthorized, or 403 forbidden errors with the following error messages.

401 Unauthorized
JSON
        {detail: "Incorrect authentication credentials. Please check or use a valid API Key"}

    
403 Forbidden
JSON
        {detail: "You do not have permission to perform this action. Please check your domains restrictions, or the referer of the API call."}

    

Best practices

Here are some guidelines you can use to determine strategies to protect your API keys.

e.g. List of private keys and associated restrictions List of Private Keys

Was this article helpful?
Have more questions? Submit a request