Authentication#
Every BeMap call is authenticated with HTTP Basic: your account is the user name, your API key is the password. There is no token to request first and nothing to renew: send the same Authorization header on every call.
curl -u 'YOUR_ACCOUNT:YOUR_API_KEY' 'https://bemap.benomad.com/bgis/service/currency/1.0/rate?code=USD'The header your client sends looks like this:
Authorization: Basic WU9VUl9BQ0NPVU5UOllPVVJfQVBJX0tFWQ==Keep the key on your server. A key embedded in a web page or a mobile application can be read by anyone who has it.
How BeMap tells you a call is not authorised#
BeMap answers each authorisation failure differently:
| What happened | What BeMap answers | What to do |
|---|---|---|
| No credentials were sent | 302 redirect to the login page | Send the Authorization header. Do not follow redirects: a client that follows this one receives 200 and an HTML login form, which then fails to parse as JSON. |
| The account or the key is wrong | 401, with a WWW-Authenticate header | Check the account name and the key. |
| The account does not have the option the service belongs to | 400 with the message Access Denied | Ask your BeNomad contact to enable the option. The same message is returned when the environment does not provide what the request asks for, such as a geocoder it does not run. |
| The key is locked to a web site and the call does not come from it | 403 with the message "Wrong site" | Call from that site, or use a key without that lock. |
Every code sample on this site disables redirect following for this reason.
Sessions#
A client that runs on your server can use a session instead: post BeMap's login form and reuse the session cookie it returns, as BeMap's own authentication guide describes. Success and failure both answer 302 with a different Location header, so read the redirect, not the status code. A web page cannot do this for another site: the browser hides the redirect from the page and does not send BeMap's cookie with a call from another origin. In a browser, send the Authorization header, through your own server.