November 29, 2023

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.

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

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:

• iOS : Bundle Id of the iOS mobile app. One key can allow multiple Bundle Ids.
• Android : Package Id and the associated SHA-1 certificate fingerprint of the signing key that was used to sign the application. One key can allow multiple Android applications.
• IP : IP or blocks of IPs authorised to request Woosmap APIs. You can list multiple IPs or blocks.

e.g. restriction setting for iOS

e.g restriction setting for server side use

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

• iOS: in Xcode in your project settings, select your target application then it’s the value in General > Identity > Bundle Identifier
• Android: the package ID is what is specified in as android > defaultConfig > applicationID of your application’s build.gradle(.kts). To obtain your certificate SHA-1 fingerprint you can run the gradle command ./gradlew :yourapplication:signingReport this will list your certificates fingerprints for all build variants. Beware if you use an applicationIdSuffix for your debug variant for example you must match the full ID with the corresponding certificate fingerprint.

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:

• X-Api-Key: your private API key
• X-iOS-Identifier: iOS only, your Bundle Id (you can call [[NSBundle mainBundle] bundleIdentifier] to obtain it)
• X-Android-Identifier: Android only, your Package Id (you can read it from the application’s context in the packageName property)
• X-Android-Fingerprint: Android only, your SHA-1 certificate fingerprint

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.

• Avoid to use the wildcard * - allow API calls from everywhere on the web - as your Public API Key domain restriction. During QA stage, use localhost or dedicated domains instead of the “*”.
• Never share API keys between server-side and client-side applications.
• Never use a private key with write permission from a public distributed application or website.
• Delete Private API keys you no longer need.
• Do not leave Private API keys without restrictions (they are signaled with a warning symbol in your API key list).

e.g. List of private keys and associated restrictions

Was this article helpful?

Have more questions? Submit a request