Getting Started Guide

Proton is the API middleware of IWG — a set of REST APIs covering locations, sales leads, inventory, and more.

This guide walks you through the four things you need to do before you can call any Proton endpoint: sign up, subscribe to a product, get your subscription key, and make your first request. It is written so you can copy/paste and be successful even if you have never used the APIs before.

What you'll finish with

You have a developer portal account
You're subscribed to at least one Product
You have a subscription key and can send it on the Ocp-Apim-Subscription-Key header
You've made a successful 2xx request against UAT
You understand when a Bearer token is required and how to get one

1) Sign up

To access the developer portal, register an account:

UAT signup: https://protonuat.developer.azure-api.net/signup

After signing up, the system sends a notification email to you and to the team that will activate your subscription. Account approval is required before you can subscribe to any product.

UAT and Production are separate environments with separate portal accounts and separate keys. Start in UAT and only move to PROD once your integration is verified.

2) Subscribe to a Product

The portal organises content into a hierarchy:

Product — a group of REST APIs covering a business journey (e.g. Locations Journey, Sales Leads).
API — a set of endpoints inside a Product (e.g. Locations).

Endpoint — a single operation defined by an HTTP verb and a URL, e.g.:

GET https://api.proton-graph.cloud/public/locations/api/v2/locationfeatures/{id}[?mode]

Request parameters — path, query, and body parameters.
Request headers — header names recognised by an endpoint (e.g. Ocp-Apim-Subscription-Key).
Responses — JSON representations of response models and the possible status codes.
Code samples — short samples in various languages.

Once your account is approved, request a subscription to the Product you need. The IWG API Portal Admin will be notified and will approve the subscription if all prerequisites are satisfied.

3) Get your subscription key (mandatory)

When your subscription is approved, two subscription keys are issued — a Primary and a Secondary. Either one works; the pair exists so you can rotate without downtime. You can also regenerate them at any time from the Profile page in the portal.

Pass the key as a header on every request:

Ocp-Apim-Subscription-Key: <YOUR_KEY>

⚠️ Treat this key as a secret. Don't share it via email or chat, don't commit it to source control, and don't hardcode it into a public website. IWG Admin can deactivate a key at any time.

UAT and PROD keys are environment-specific and cannot be used across environments.

4) Make your first request

4.1 Base URL

UAT (test): https://api-uat.proton-graph.cloud
PROD (live): https://api.proton-graph.cloud

4.2 Endpoint URL structure

Endpoint URLs follow this pattern:

{VERB} {baseUrl}/public/{apiName}/api/{version}/{entity}/{param}[?mode]

Concretely, the pieces map as follows:

`{VERB}`	`{baseUrl}`	`/public/`	`{apiName}`	`/api/`	`{version}/`	`{entity}`	`/{param}[?mode]`
`GET`	`https://api.proton-graph.cloud`	`/public/`	`locations`	`/api/`	`v2/`	`locationfeatures`	`/1?mode=Extended`

So, to query a specific location feature entity:

GET https://api.proton-graph.cloud/public/locations/api/v2/locationfeatures/1?mode=Extended

4.3 Working cURL example

Use this against UAT first to confirm everything is wired up. Replace <YOUR_KEY> with your subscription key.

curl -X GET "https://api-uat.proton-graph.cloud/public/locations/api/v2/locationfeatures/1?mode=Extended" \
  -H "Ocp-Apim-Subscription-Key: <YOUR_KEY>" \
  -H "Accept-Language: en-GB" \
  -H "Content-Type: application/json"

A successful request returns a 2xx response. If you get 401/403, jump to Troubleshooting.

Some endpoints reply with 202 Accepted and a jobId instead of the entity — these run asynchronously. See Deferred Jobs when you hit one.

5) Request headers reference

These are the headers Proton recognises on every request:

Mandatory	Key	Value	Source	Notes
Optional	`Accept-Language`	`fr-FR`	Client	Defaults to `en-*` if not provided.
Yes	`Ocp-Apim-Subscription-Key`	`<YOUR_KEY>`	APIM Subscription	Mandatory for accessing the API. Either Primary or Secondary key works.
Conditional	`Authorization`	`Bearer <YOUR_TOKEN>`	Identity Server	Mandatory only for endpoints that handle sensitive data — see section 6.
Optional	`Content-Type`	`application/json`	Client	Metadata about the request body.

6) Bearer Token — only if required

Some endpoints require a second level of authorisation from the IWG Identity Server. You'll know an endpoint requires a Bearer token because the API definition lists Authorization as a required header.

You don't create this token yourself — Proton authorities will issue you a clientId and clientSecret, which you exchange for a token via the Admin API's Get token by identifier and secret endpoint. Then send it on every request that needs it:

Authorization: Bearer <YOUR_TOKEN>

Treat clientId and clientSecret the same way you treat your subscription key — never commit them, never share them with other parties.

Best practice: tokens are long-lived and renewable. Cache and reuse the token until close to its expiry date — don't request a new token for every API call.

7) Common Proton properties

These fields appear on most Proton entities. Worth knowing before you start parsing responses:

Field	Type	Notes
`Id`	`string`	Even when the underlying value is numeric or a GUID, Proton normalises it to a string by design.
`ExternalReferenceIds`	`List<ExternalReferenceInfo>`	References of this entity in other systems. Each entry has a `SystemName` and `Identifier`.
`TimeStamp`	`string`	Maps to the underlying ETag. Required when modifying or deleting an entity you previously fetched, to avoid a `409 Conflict`.
`Links`	`List<RestLink>`	HATEOAS links. Each entry has a `Rel`, `Href`, and `Method`.
`CreateDate`	`DateTime`	When the entity was created in Proton.
`IsDeleted`	`bool`	Soft-delete flag — Proton marks deleted entities rather than removing them.

8) Self-check before going live

Run through these in UAT before requesting PROD access:

Test 1 — Happy path

Send the cURL example in section 4.3 → expect 2xx.

Test 2 — Auth failure

Send the same request without the Ocp-Apim-Subscription-Key header → expect 401. This confirms your error handling.

Test 3 — Bearer-protected endpoint (if applicable)

If your Product includes restricted endpoints, exchange your clientId/clientSecret for a token, then call a protected endpoint with both headers → expect 2xx.

Test 4 — Deferred job (if applicable)

If your Product exposes async operations, follow the Deferred Jobs self-check.

9) Moving to PROD (live traffic)

When you're ready for PROD:

Create a PROD portal account — use a service/integration account, not a personal one.
Subscribe to the same Product(s) and obtain a PROD subscription key.
Switch only:
- the base URL (api-uat.proton-graph.cloud → api.proton-graph.cloud)
- the subscription key
- any Bearer clientId/clientSecret issued for PROD

Everything else — endpoint paths, request shapes, headers — stays the same.

Your PROD portal account is also used as the technical contact for your company if we need to reach you.

10) Troubleshooting

401 Unauthorized / 403 Forbidden

Missing Ocp-Apim-Subscription-Key header.
Wrong key (UAT key used against PROD or vice-versa).
Subscription not yet approved, or key has been deactivated.
Endpoint requires a Bearer token and you didn't send one (or it's expired).

400 Bad Request

Invalid payload — missing required fields or wrong types.
Wrong date format (use ISO 8601, e.g. 2026-01-15T12:31:22.000Z).
Country code in the wrong format (some endpoints expect ISO3, e.g. GBR, not ISO2 GB).

404 Not Found

Wrong base URL or wrong path — double-check {apiName}, {version}, and {entity}.

409 Conflict (on update/delete)

Missing or stale TimeStamp on the request — re-fetch the entity and resend with the latest TimeStamp.

"No BrokerContactId supplied in claims"

Your account provisioning hasn't been fully completed. Open a ticket via the Customer Support Portal.

11) Getting help

When you're onboarded, a Customer Support Portal account is created for one of your named contacts — preferably a service email (e.g. svc_proton_integration@mycompany.com) rather than a personal one.

Before raising a support ticket, check the API status page for any ongoing incidents.