Use API keys to authenticate
API keys are available to use only with map,
place, and route resources, and you can't modify or create those resources. If
your application needs access to other resources or actions for unauthenticated
users, you can use Amazon Cognito to provide access along with, or instead of, API keys.
For more information, see Use Amazon Cognito to authenticate.
API keys are a key value that is associated with
specific Amazon Location Service resources or API in your AWS account, and specific actions that you
can perform on those resources. You can use an API key in your application to make
unauthenticated calls to the Amazon Location APIs for those resources.
For example, if you associate an API key with a resource and/or the
GetPlace* API, then an application that uses that API key will be able
to call specific APIs. That same API key would not give permissions to change or update
any resource or call APIs that it isn't associated with.
When you call Amazon Location Service APIs in your applications, you typically make this call as an
authenticated user who is authorized to make the
API calls. However, there are some cases where you don't want to authenticate every user
of your application.
For example, you might want a web application that shows your business location to be
available to anyone using the website, whether they are logged in or not. In this case,
one alternative is to use API keys to make the API calls.
See Best practices for API keys for additional information about when to
use API keys.
For more information about working with keys using the Amazon Location Service API, see the following
topics in the Amazon Location Service API Reference:
Create an API key for Amazon Location Service
You can create an API key through the Amazon Location Service console, AWS CLI, or Amazon Location API.
Continue with the appropriate procedures below.
- Amazon Location console
-
To create an API key using the Amazon Location Service console
-
In the Amazon Location console, choose
API keys from the left menu.
-
On the API keys page, choose
Create API key.
-
On the Create API key page,
fill in the following information:
-
Name – A name for your API
key, such as ExampleKey.
-
Description – An optional
description for your API key.
-
Resources – In the
dropdown, choose the Amazon Location resources to give access
to with this API key. You can add more than one resource
by choosing Add resource.
-
Actions – Specify the
actions you want to authorize with this API key. You
must select at least one action to match each resource
type you have selected. For example, if you selected a
place resource, you must select at least one of the
choices under Places
Actions.
-
Expiration time –
Optionally, add an expiration date and time for your API
key. For more information, see Best practices for API keys.
-
Client restrictions –
Optionally, add one or more web domains or one or more
Android or Apple apps where you can use the API key. For
example, if the API key is to allow an application
running on the website example.com, then
you could put *.example.com/ as an allowed
referrer.
-
Tags – Optionally, add
tags to the API key.
-
Choose Create API key to create the API
key.
-
On the detail page for the API key, you can see information
about the API key that you have created. Choose Show
API key to see the key value that you use when
calling Amazon Location APIs. The key value will have the format
v1.public.a1b2c3d4....
- AWS CLI
-
-
Use the create-key command. The following example creates
an API key called ExampleKey with no expiration
date and access to a single map resource.
aws location \
create-key \
--key-name ExampleKey \
--restrictions '{"AllowActions":["geo-maps:*"],"AllowResources":["arn:aws:geo-maps:region::provider/default"]}' \
--no-expiry
-
The response includes the API key value to use when accessing
resources in your applications. The key value will have the
format v1.public.a1b2c3d4.... To learn more about
using the API key to render maps, see Use an API key to call an Amazon Location API. The response to create-key
looks like the following:
{
"Key": "v1.public.a1b2c3d4...",
"KeyArn": "arn:aws:geo:region:accountId:api-key/ExampleKey",
"KeyName": "ExampleKey",
"CreateTime": "2023-02-06T22:33:15.693Z"
}
-
You can also use describe-key to find the key
value at a later time. The following example shows how to call
describe-key on an API key named
ExampleKey.
aws location describe-key \
--key-name ExampleKey
- Amazon Location API
-
Use the CreateKey operation from the Amazon Location APIs. The following
example is an API request to create an API key called
ExampleKey with no expiration date and access to a
single map resource.
POST /metadata/v0/keys HTTP/1.1
Content-type: application/json
{
"KeyName": "ExampleKey",
"NoExpiry": true,
"Restrictions": {
"AllowActions": [
"geo-places:*",
"geo-routes:*",
"geo-maps:*"
],
"AllowResources": [
"arn:aws:geo-places:Region::provider/default",
"arn:aws:geo-routes:Region::provider/default",
"arn:aws:geo-maps:Region::provider/default"
]
}
}
The response includes the API key value to use when accessing
resources in your applications. The key value will have the format
v1.public.a1b2c3d4....
You can also use the DescribeKey API to find the key value for a key at a later
time.
Use an API key to call an Amazon Location API
After you create an API key, you can use the key value to make calls to Amazon Location
APIs in your application.
- API
-
The APIs that support API keys have an additional parameter that takes
the API key value. For example, if you call the GetPlace
API, you can fill in the key parameter, as follows
curl --request GET —url 'https://places.geo.eu-central-1.amazonaws.com/v2/place/{PLACEID}?key={APIKEY}&language=jp'
- AWS CLI
-
When you use the --key parameter, you should also use the
--no-sign-request parameter, to avoid signing with Sig
v4.
aws geo-places get-place --place-id $PLACEID --language jp --key $APIKEY
- SDK (web)
-
Use the following code:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Display a map</title>
<meta property="og:description" content="Initialize a map in an HTML element with MapLibre GL JS." />
<meta charset='utf-8'>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel='stylesheet' href="/https://unpkg.com/maplibre-gl@5.x/dist/maplibre-gl.css" />
<script src="/https://unpkg.com/maplibre-gl@5.x/dist/maplibre-gl.js"></script>
<style>
body { margin: 0; }
#map { height: 100vh; }
</style>
</head>
<body>
<div id="map"></div>
<script>
const apiKey = "<api key>"; // check how to create api key for Amazon Location
const mapStyle = "Standard"; // eg. Standard, Monochrome, Hybrid, Satellite
const awsRegion = "eu-central-1"; // eg. us-east-2, us-east-1, us-west-2, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ca-central-1, eu-central-1, eu-west-1, eu-west-2, eu-south-2, eu-north-1, sa-east-1
const styleUrl = `https://maps.geo.${awsRegion}.amazonaws.com/v2/styles/${mapStyle}/descriptor?key=${apiKey}`;
const map = new maplibregl.Map({
container: 'map', // container id
style: styleUrl, // style URL
center: [25.24,36.31], // starting position [lng, lat]
zoom: 2, // starting zoom
});
</script>
</body>
</html>
- SDK (iOS, Swift)
-
Use the following code:
import UIKit
import MapLibre
class ViewController: UIViewController {
let apiKey = "Enter your API key" // The previously-created API Key to use
let regionName = "Enter your region name" // The service region - us-east-1, ap-south-1, etc
var mapView: MLNMapView!
override func viewDidLoad() {
super.viewDidLoad()
loadMap()
}
func loadMap() {
let styleName = "Standard" // The map style - Standard, Monochrome, Hybrid, Satellite
let colorName = "Light" // The color scheme - Light, Dark
// The Amazon Location Service map style URL that MapLibre will use to render the maps.
let styleURL = URL(string: "https://maps.geo.\(regionName).amazonaws.com/v2/styles/\(styleName)/descriptor?key=\(apiKey)&color-scheme=\(colorName)")
// Initialize MapLibre
mapView = MLNMapView(frame: view.bounds)
mapView.styleURL = styleURL
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
// Set the starting camera position and zoom level for the map
mapView.setCenter(CLLocationCoordinate2D(latitude: 49.246559, longitude: -123.063554), zoomLevel: 10, animated: false)
view.addSubview(mapView!)
}
}
- SDK (Android, Kotlin)
-
Use the following code:
class MapActivity : Activity(), OnMapReadyCallback {
private lateinit var mBinding: ActivityMapBinding
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
initializeMap(savedInstanceState)
}
private fun initializeMap(savedInstanceState: Bundle?) {
// Init MapLibre
// See the MapLibre Getting Started Guide for more details
// https://maplibre.org/maplibre-native/docs/book/android/getting-started-guide.html
MapLibre.getInstance(this@MapActivity)
mBinding = ActivityMapBinding.inflate(layoutInflater)
setContentView(mBinding.root)
mBinding.mapView.onCreate(savedInstanceState)
mBinding.mapView.getMapAsync(this)
}
override fun onMapReady(mapLibreMap: MapLibreMap) {
mapLibreMap.setStyle(Style.Builder().fromUri(getMapUrl())) {
// Set the starting camera position
mapLibreMap.cameraPosition = CameraPosition.Builder().target(LatLng(49.246559, -123.063554)).zoom(10.0).build()
mapLibreMap.uiSettings.isLogoEnabled = false
mapLibreMap.uiSettings.attributionGravity = Gravity.BOTTOM or Gravity.END
mapLibreMap.uiSettings.setAttributionDialogManager(AttributionDialogManager(this, mapLibreMap))
}
}
// Return the Amazon Location Service map style URL
// MapLibre will use this to render the maps.
// awsRegion: The service region - us-east-1, ap-south-1, etc
// mapStyle: The map style - Standard, Monochrome, Hybrid, Satellite
// API_KEY: The previously-created API Key to use
// colorName: The color scheme to use - Light, Dark
private fun getMapUrl() =
"https://maps.geo.${getString(R.string.awsRegion)}.amazonaws.com/v2/styles/${getString(R.string.mapStyle)}/descriptor?key=${BuildConfig.API_KEY}&color-scheme=${getString(R.string.colorName)}"
override fun onStart() {
super.onStart()
mBinding.mapView.onStart()
}
override fun onResume() {
super.onResume()
mBinding.mapView.onResume()
}
override fun onPause() {
super.onPause()
mBinding.mapView.onPause()
}
override fun onStop() {
super.onStop()
mBinding.mapView.onStop()
}
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mBinding.mapView.onSaveInstanceState(outState)
}
override fun onLowMemory() {
super.onLowMemory()
mBinding.mapView.onLowMemory()
}
override fun onDestroy() {
super.onDestroy()
mBinding.mapView.onDestroy()
}
}
