The XMAP Hub API can authenticate calls from your own systems (a CRM, a Power Platform flow, a back-office integration) using OAuth 2.0 with tokens issued by your council's own Microsoft Entra ID tenant. You keep full control of the credentials: you create them, you rotate them, and you can switch them off at any time without contacting Geoxphere.

This article explains how the two sides fit together and walks through the setup. It is written for an Entra administrator working with the person who owns the integration.

How it works

Every OAuth call involves two applications:

• XMAP API is Geoxphere's application. It represents the API being called. It lives in Geoxphere's tenant and is published as a multi-tenant application, so other organisations can grant permissions to it. You do not create or copy this application.
• Your client application is a small application you register in your own tenant. It represents the system that will call the Hub API and holds the secret or certificate that system uses to prove who it is.

When an administrator in your tenant grants your client application permission to use XMAP API, Entra automatically creates an entry for XMAP API under Enterprise applications in your tenant. That entry is what links the two tenants. It is also your off switch: disabling it blocks every token for the Hub API from your tenant.

Your system then asks your tenant for a token, using the client credentials grant (no user signs in). The token names XMAP API as its audience and lists the permissions your administrator granted. The Hub API checks that the token came from a tenant Geoxphere has recorded for your council, that it is signed by your tenant, and that it carries the permission the endpoint needs.

Note: The permissions are application permissions (sometimes shown as app roles), not delegated permissions. Application permissions are the only kind that can appear in a token requested without a signed-in user.

Prerequisites

• An Entra role that can register applications and grant admin consent: Application Administrator or Cloud Application Administrator (Global Administrator also works).
• The values Geoxphere gives you: the XMAP API application ID and the base URL of the Hub API for your council.
• An agreement with Geoxphere about which endpoints your integration will call, so the right permissions are enabled on your council's account.

Permissions available

Request only the permissions your integration needs. Each endpoint checks for its own permission.

Steps

1. Make XMAP API visible in your tenant

Because XMAP API belongs to another organisation, it has to be linked into your tenant once before it appears in any permission list. Choose either method:

1. Consent link (simplest). Open the admin consent link Geoxphere provides, sign in as an administrator, and accept. The link looks like https://login.microsoftonline.com/<your tenant ID>/adminconsent?client_id=<XMAP API application ID>&redirect_uri=https://oauth.hub.xmap.cloud/oauth/consented.html. After you accept, a confirmation page on oauth.hub.xmap.cloud shows your tenant ID with a copy button, ready for step 5.
2. Command line (alternative). Signed in to your tenant, run one of:

   # Azure CLI
   az ad sp create --id <XMAP API application ID>
   
   # Microsoft Graph PowerShell
   New-MgServicePrincipal -AppId "<XMAP API application ID>"

Afterwards, Enterprise applications in your tenant lists an application called XMAP API.

2. Register your client application

1. In the Microsoft Entra admin centre, go to Identity > Applications > App registrations and click New registration.
2. Give it a name that identifies the calling system, for example CRM to XMAP Hub.
3. Leave Supported account types as Accounts in this organizational directory only.
4. Leave Redirect URI empty. A system-to-system client does not need one.
5. Click Register.
6. On the Overview page, note the Application (client) ID and the Directory (tenant) ID. You will send both to Geoxphere.

3. Create a credential

1. Open Certificates & secrets.
2. Preferred: upload a certificate under Certificates. Otherwise, under Client secrets click New client secret, choose an expiry, and click Add.
3. Copy the secret Value immediately and store it in your secrets manager. It is shown only once.

Warning: Set a calendar reminder before the secret expires. An expired secret stops the integration with an authentication error on the token request.

4. Grant the XMAP API permissions

1. Open API permissions and click Add a permission.
2. Select the APIs my organization uses tab and search for XMAP API. You can also paste the application ID into the search box.
3. Select Application permissions (not Delegated permissions).
4. Tick Hub.Custom and/or Hub.Report, then click Add permissions.
5. Click Grant admin consent for <your organisation> and confirm. The Status column shows a green tick for each permission.

Note: If XMAP API does not appear in the list, step 1 has not been completed in your tenant. Permissions only take effect after admin consent is granted; without it, tokens are issued but contain no permissions and the Hub API returns 403.

5. Send Geoxphere the identifiers

Email your Geoxphere contact or raise a support ticket with:

• Your Directory (tenant) ID
• The Application (client) ID of your client application
• Which permissions you granted and which endpoints you will call

Never send the client secret. Geoxphere does not need it and will not ask for it.

Geoxphere records your tenant and client against your council's account. Until that is done, valid tokens from your tenant are refused with 403 Not authorised.

6. Request a token and call the API

Your system requests a token from your tenant, then sends it as a bearer token to the Hub API. Replace the placeholders with your values.

POST https://login.microsoftonline.com/<your tenant ID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your client application ID>
&client_secret=<your client secret>
&scope=api://<XMAP API application ID>/.default

The response contains access_token and expires_in (typically 3,600 to 5,400 seconds). Then:

GET https://<hub api host>/<council id>/custom/<endpoint id>?x=403163.94&y=301844.54
Authorization: Bearer <access_token>

A complete example with curl:

TOKEN=$(curl -s -X POST "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id="$CLIENT_ID" \
  --data-urlencode client_secret="$CLIENT_SECRET" \
  --data-urlencode scope="api://$XMAP_API_APP_ID/.default" | jq -r .access_token)

curl -H "Authorization: Bearer $TOKEN" \
  "https://$HUB_API_HOST/$COUNCIL_ID/custom/$ENDPOINT_ID?x=403163.94&y=301844.54"

Note: The value /.default at the end of the scope is required for the client credentials grant. It means "all the application permissions this client has been granted for XMAP API". Do not replace it with a permission name.

Good practice for your integration

• Cache the token and reuse it until shortly before expires_in. Do not request a new token for every API call.
• Handle 401 by requesting a fresh token once and retrying. If it fails again, the credential is probably wrong or expired.
• Handle 429 by waiting for the number of seconds in the Retry-After header. The Hub API applies a per-address rate limit.
• Handle 503 by retrying after the Retry-After value. It means the Hub API could not reach Entra to check the token's signature.
• Rotate secrets by adding a new one, switching your system to it, then deleting the old one. You do not need to tell Geoxphere.

Switching access off

You can stop your integration calling the Hub API at any time, without involving Geoxphere:

• Delete the client secret or certificate, or delete the client application registration. New tokens can no longer be issued.
• Or open Enterprise applications, select XMAP API, and set Enabled for users to sign in? to No. This blocks every client in your tenant from getting a Hub API token.

Tokens already issued remain valid until they expire (at most about 90 minutes). If you need access stopped immediately, also ask Geoxphere to remove your tenant from your council's configuration, which takes effect on the next request.

Troubleshooting