Source: https://developers.woosmap.com/api-reference/authentication/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Authentication ## 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](https://www.woosmap.com/en/sign_up/). Steps: 1. Visit the [Woosmap Console](https://console.woosmap.com/) 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](/assets/images/support/screenshot-restrict-api-key-woosmap.jpg) ## Registering a Woosmap Private API key Assuming you have already created your [Woosmap account](https://www.woosmap.com/en/sign_up/). Steps: 1. Visit the [Woosmap Console](https://console.woosmap.com/) 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](/assets/images/support/Add_new_private_key_with_name.png) 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 ![Add restriction for iOS integration](/assets/images/support/Add_new_private_key_iOS_added.png) e.g restriction setting for server side use ![Add restriction for IP](/assets/images/support/Add_new_private_key_IP_added.png) To find out the values you'll need for mobile restrictions, see [Getting Platform Identifiers](#getting-platform-identifiers) below. ## Authenticating from Mobile Apps or Server-Side via Headers As an alternative to query parameters, you can authenticate using HTTP headers. This is the recommended approach for mobile applications and is also useful for server-side integrations where you prefer not to include keys in URLs. All Woosmap REST APIs accept the following header: - `X-Api-Key`: your **private API key** When calling from a mobile application with a restricted private key, you must also include platform identification headers so the restriction can be validated: - `X-iOS-Identifier`: iOS only, your **Bundle Id** - `X-Android-Identifier`: Android only, your **Package Id** - `X-Android-Fingerprint`: Android only, your **SHA-1 certificate fingerprint** Our [mobile SDKs](/products/mobile/get-started/) set these headers automatically. If you're using the Woosmap SDK, you don't need to configure them manually. ### Examples ```bash curl -H "X-Api-Key: YOUR_PRIVATE_KEY" \ "https://api.woosmap.com/localities/autocomplete/?input=paris" ``` ```swift var request = URLRequest(url: URL(string: "https://api.woosmap.com/localities/autocomplete/?input=paris")!) request.setValue("YOUR_PRIVATE_KEY", forHTTPHeaderField: "X-Api-Key") request.setValue(Bundle.main.bundleIdentifier, forHTTPHeaderField: "X-iOS-Identifier") ``` ```kotlin val request = Request.Builder() .url("https://api.woosmap.com/localities/autocomplete/?input=paris") .addHeader("X-Api-Key", "YOUR_PRIVATE_KEY") .addHeader("X-Android-Identifier", context.packageName) .addHeader("X-Android-Fingerprint", "YOUR_SHA1_FINGERPRINT") .build() ``` ```dart final response = await http.get( Uri.parse('https://api.woosmap.com/localities/autocomplete/?input=paris'), headers: { 'X-Api-Key': 'YOUR_PRIVATE_KEY', // Add platform headers if using a restricted key: // On iOS: // 'X-iOS-Identifier': 'com.example.bundle.id', // On Android: // 'X-Android-Identifier': 'com.example.app', // 'X-Android-Fingerprint': 'YOUR_SHA1_FINGERPRINT', }, ); ``` ### Getting Platform Identifiers - **iOS Bundle Id**: In Xcode, find it under your target's General > Identity > Bundle Identifier, or call `Bundle.main.bundleIdentifier` at runtime. - **Android Package Id**: Read it from your application context via `context.packageName`. It must match the `applicationId` in your `build.gradle(.kts)`, including any `applicationIdSuffix`. - **Android SHA-1 Fingerprint**: Run `./gradlew :yourapp:signingReport` to list certificate fingerprints for all build variants. Make sure to use the fingerprint matching your signing configuration. ## 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. ```json {detail: "Incorrect authentication credentials. Please check or use a valid API Key"} ``` ```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 ![List of Private Keys](/assets/images/support/New_private_key_restrictions_set.png)