Getting started

apiConnect is the Markel API gateway. It gives internal teams and approved partners one secure, monitored way to discover and call Markel APIs. This guide takes you from your first sign-in to your first successful API call.

1. Sign in

Select Sign in and use your Markel account. Your developer profile is created automatically the first time you sign in, and the APIs, products and API Status pages become available in the menu.

2. Find an API

Open the API catalog and search by name or tag. Each API page lists its operations with request parameters, headers, request and response schemas, and examples. Use Try it to send a real request from your browser.

3. Get a subscription key on the API page

Above the operation details, the Get a subscription key panel shows the product that contains the API. Select Get a key to subscribe instantly, or Request access when the product needs approval; you will receive an email once the apiConnect team approves it. When you are subscribed, select Show keys to view, copy or regenerate your primary and secondary keys.

Every subscription has two keys, so you can switch your application to one while you regenerate the other without downtime. All your subscriptions are also listed on your profile.

4. Try it in the console

Refresh the API page after subscribing, open an operation and select Try it. In the Authorization section choose your subscription, then select Authorization code and sign in with your Markel account. The console adds both the subscription key and the access token to the request.

5. Call the API from your application

Send your key in the Ocp-Apim-Subscription-Key header on every request, together with an OAuth access token in the Authorization header. The full request URL for each operation is shown on its API page. For example:

GET https://<gateway-host>/<api-path>/<operation>

Ocp-Apim-Subscription-Key: <your-key>

Authorization: Bearer <access-token>

A 401 response means the key or access token is missing, wrong or expired, and a 403 response means your subscription does not include that API or is not active yet.

Environments

apiConnect runs separate dev, qa, uat, mirror and prod environments, each with its own portal and keys. Build and test against a lower environment first, and request a production subscription only when your integration is ready.

Good practice

• Keep keys out of source control and client-side code. Store them in a secret store such as Azure Key Vault.

• Regenerate a key immediately if you think it has been exposed.

• Respect rate limits. Retry 429 and 5xx responses with exponential back-off rather than immediately.

• Log the response request id so issues can be traced at the gateway.

• Check API Status before raising an incident.

Need help?

Visit Support for how to contact the apiConnect team.