Skip to content
Makani Global
Create account
Developers

API key scopes and restrictions

Give each key only what it needs: scopes, countries, products and where it may be used from.

Base URLhttps://makani-k8s.lamah.com

Scopes

A scope opens a group of endpoints. Choose them when you create the key; a request outside them answers 403 API_KEY_SCOPE_DENIED. A scope also needs the matching feature in your plan.

  • addresses:searchSearch addresses by text.
  • addresses:resolveReverse lookup from a point, and the areas that contain it.
  • addresses:readRead an address by its fields, its code or its id, and batch lookups.
  • addresses:writeSubmit addresses for review and read their outcome.
  • addresses:sensitive:readFields a country marks sensitive, when your plan allows them.
  • maps:readAddress points for a map viewport, as GeoJSON.
  • routing:routeRoute, directions, best stop order, reachable area and trace.
  • routing:matrixDistance matrix.
  • routing:readRoad closures for your map.
  • diagnostics:writeReport trips, positions and events.
  • reports:writeSend problem reports from your users, with a photo.
  • reports:readRead the reports your project sent and their status.
  • zones:readRead your zones and ask which ones contain a point.
  • zones:writeAdd, change and delete your zones.

Countries, products and expiry

A key can be narrowed further:

  • Countries: only the listed country codes. Other countries answer 403 API_KEY_COUNTRY_DENIED.
  • Products: only some of addresses, address submissions, maps, routing and diagnostics. Other products answer 403 API_KEY_PRODUCT_DENIED.
  • Expiry: a date after which the key stops working.

Application restrictions

A key carries one application restriction, which says where requests may come from. A request from anywhere else answers 403 API_KEY_RESTRICTED. Up to 100 entries each.

  • Websites: patterns such as example.com, *.example.com or https://app.example.com/maps/*, matched against the request's Origin or Referer.
  • IP addresses: single addresses or CIDR ranges, IPv4 and IPv6, such as 203.0.113.0/24. Use this for servers.
  • Android apps: the package name and the SHA-1 of the signing certificate, sent as x-android-package and x-android-cert.
  • iOS apps: the bundle identifier, sent as x-ios-bundle-identifier.

An Android or iOS app sends its identity in headers with every request:

GET/v1/addresses/{countryCode}/searchScopeaddresses:search
curl "https://makani-k8s.lamah.com/v1/addresses/QA/search?q=Street%20984&locale=en&limit=5" \  -H "x-api-key: $MAKANI_API_KEY" \  -H "x-android-package: com.example.app" \  -H "x-android-cert: AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01"

Rotating and revoking

Rotate a key in the console to get a new secret. You can keep the old key working beside the new one for up to 30 days, so your apps switch without an outage. Revoking stops a key at once.

Key errors

What a refused key answers:

  • 401API_KEY_REQUIREDThe request carries no key.
  • 401API_KEY_INVALIDThe key is unknown or revoked.
  • 401API_KEY_EXPIREDThe key has passed its expiry date. Create or rotate a key in the console.
  • 403API_KEY_SCOPE_DENIEDThe key lacks the scope the endpoint needs. message names it.
  • 403API_KEY_COUNTRY_DENIEDThe key is not enabled for this country, whether the request names it in the path, the query or the body.
  • 403API_KEY_PRODUCT_DENIEDThe key is not enabled for this product.
  • 403API_KEY_RESTRICTEDThe request does not come from the website, address or app the key is restricted to.