Introduction

Akumina AI uses Azure AI Document Intelligence (formerly Form Recognizer) to read the documents it indexes — extracting text, tables, key–value pairs, and structured fields from PDFs, images, and Office files so that their content can be chunked, embedded, and searched. Every Akumina AI deployment that indexes documents needs a Document Intelligence resource.

How Akumina AI reaches that resource is a deployment choice, and this guide covers both supported options:

Both paths start the same way: create the Document Intelligence resource and copy its key and endpoint. A direct configuration stops there. An APIM configuration takes the same key and endpoint and places them in the gateway rather than in the client, so that the client only ever holds a gateway subscription key.

Getting started with Document Intelligence

Follow this section for every deployment, whether or not you intend to put a gateway in front of the service. It produces a working, directly connected configuration.

Create the Document Intelligence resource

In the Azure portal, choose Create a resource, search for Document Intelligence, and select Create. Supply the subscription, resource group, region, and a resource name, choose a pricing tier — F0 (free) is adequate for evaluation, S0 for production — and complete the wizard. Deployment takes a minute or two.

Copy the keys and endpoint

Open the resource and go to Keys and Endpoint. This blade holds the values that every other part of this guide refers to.

Configure the Embeddings section in Akumina AI settings

In the Akumina AI settings, go to Settings › AI Settings and open the EmbeddingConfiguration section. The two values you just copied go into the AzureDocumentIntelligence block inside it:

A direct — non-APIM — Document Intelligence configuration therefore looks like this:

"EmbeddingConfiguration": {
    "TextEmbeddingType": "AzureOpenAI",
    "AudioEmbeddingType": "AzureOpenAIWhisper",
    "AzureDocumentIntelligence": {
        "Enabled": true,
        "Extensions": [ "png", "jpeg", "jpg", "xlsx" ],
        "ApiKey": "<KEY 1 or KEY 2 from Keys and Endpoint>",
        "Endpoint": "https://<docintel-resource>.cognitiveservices.azure.com"
    },
    "ChunkSize": {
        "ParagraphsPerPage": 10,
        "LinesPerPage": 40,
        "TokensPerPage": 0
    }
}

Save the settings. Note that AdditionalHeaders is absent here: the resource key is the credential and the client sends it itself. That block exists for the gateway case, where a second credential — the APIM subscription key — has to travel alongside every request under a header name the gateway chooses.

Validate the direct connection

Before pointing Akumina AI at the resource, confirm that the endpoint and key work together. Analysis is a long-running operation, so validation is two calls: submit a document, then poll for the result. The examples use Windows cmd.exe continuation (^) and escaped double quotes; on bash use \ and single quotes instead.

curl -i -X POST "https://<docintel-resource>.cognitiveservices.azure.com/documentintelligence/documentModels/prebuilt-layout:analyze?api-version=2024-11-30" ^
  -H "Ocp-Apim-Subscription-Key: YOUR-DOCUMENT-INTELLIGENCE-KEY" ^
  -H "Content-Type: application/json" ^
  -d "{\"urlSource\":\"https://YOUR-HOST/sample.pdf\"}"

Then GET the Operation-Location value returned by the POST, with the same key:

curl "https://<docintel-resource>.cognitiveservices.azure.com/documentintelligence/documentModels/prebuilt-layout/analyzeResults/RESULT-ID?api-version=2024-11-30" ^
  -H "Ocp-Apim-Subscription-Key: YOUR-DOCUMENT-INTELLIGENCE-KEY"

Overview of the APIM configuration

Azure AI Document Intelligence (formerly Form Recognizer) extracts text, tables, key–value pairs, and structured fields from documents. This guide publishes it through Azure API Management (APIM) so that client applications call it through a managed gateway and never hold the resource key.

Document Intelligence is a separate Azure resource from Foundry — a different host, a different API surface, and its own key — so it is configured as its own APIM API. Nothing in the Foundry APIM guide changes.

The configuration is deliberately thin. Both operations use a wildcard frontend path, so the request path and query string pass through to the resource unchanged and all of the work is done by two API-level policies: the inbound policy attaches the resource key, and the outbound policy repoints the Operation-Location header at the gateway. There are no operation-level policies and no path rewriting.

How a request flows

Analysis is a long-running operation, which is why two operations are needed. The client POSTs a document and the service replies 202 Accepted with an empty body and an Operation-Location header; the client then GETs that URL until the payload reports "status": "succeeded". Results are retained by the service for 24 hours.

Prerequisites

Configuring APIM

Store the Document Intelligence key as a named value

In the APIM instance, go to Named values › + Add and create a value named docintel-key of type Secret (or Key vault), using KEY 1 or KEY 2 from the resource’s Keys and Endpoint blade.

Why. Policies reference it as {{docintel-key}}, so the key never appears in the policy document, which is readable by anyone with contributor access and is often exported to source control. Rotation is a single edit in one place. A Key Vault–backed value goes further: rotation happens in the vault and APIM refreshes automatically.

Add the API

Go to APIs › + Add API › HTTP — the blank, manually defined option, not Azure AI Foundry or OpenAPI — select Full to reveal every field, and set:

The resulting client base URL is https://<apim-host>.azure-api.net/mydocintel.

Add the two operations

On the Design tab, add two operations with + Add operation. Both use the same wildcard frontend template, and neither needs an operation-level inbound or outbound policy:

Why a wildcard. The * matches the whole remaining path, so one POST operation covers every analyze route for every model and one GET operation covers every result route. The path and the query string reach the resource exactly as the client sent them, which means:

Because both operations share one template, the method is what distinguishes them — which is exactly the split the analyze-and-poll cycle needs.

API-level inbound policy

Open All operations › Inbound processing › policy code editor and set:

<inbound>
    <base />
    <set-header name="Ocp-Apim-Subscription-Key" exists-action="override">
        <value>{{docintel-key}}</value>
    </set-header>
</inbound>

Why. Document Intelligence reads its key from Ocp-Apim-Subscription-Key. This is the only change the request needs: the API’s web service URL already points at the resource and the wildcard leaves the path alone.

API-level outbound policy

In Outbound processing on the same All operations scope, set:

<outbound>
    <base />
    <choose>
        <when condition="@(context.Response.Headers.ContainsKey(&quot;Operation-Location&quot;))">
            <set-header name="Operation-Location" exists-action="override">
                <value>@(context.Response.Headers.GetValueOrDefault(&quot;Operation-Location&quot;,&quot;&quot;)
                    .Replace(&quot;https://YOUR-DOCINTEL-RESOURCE.cognitiveservices.azure.com&quot;,
                             &quot;https://YOUR-APIM-HOST.azure-api.net/mydocintel&quot;))</value>
            </set-header>
        </when>
    </choose>
</outbound>

Replace the first string with your Document Intelligence endpoint and the second with your gateway base URL — the host plus the API URL suffix from Add the API. Neither may have a trailing slash, and both must include the scheme; Replace is a literal, case-sensitive match, so a mismatch silently leaves the header untouched.

Why. The 202 response carries Operation-Location built from the resource’s own hostname. A client that follows it verbatim leaves the gateway, reaches the resource directly, and is rejected with 401 — it holds an APIM subscription key, not the resource key. Swapping the host in the header keeps the whole analyze-and-poll cycle inside the gateway.

The choose guard means responses without the header — the poll responses, and any error returned by the service — pass through untouched. Note also that the expression uses Replace rather than a comparison: a policy document is XML, so a bare < inside an expression makes the policy fail to save.

Validate with curl

Validate the gateway before pointing an application at it. The examples use Windows cmd.exe continuation (^) and escaped double quotes; on bash use \ and single quotes instead. The placeholders deliberately avoid angle brackets — < and > are redirection operators in cmd.exe.

POST — submit a document

curl -i -X POST "https://YOUR-APIM-HOST.azure-api.net/mydocintel/documentintelligence/documentModels/prebuilt-layout:analyze?api-version=2024-11-30" ^
  -H "api-key: YOUR-APIM-SUBSCRIPTION-KEY" ^
  -H "Content-Type: application/json" ^
  -d "{\"urlSource\":\"https://YOUR-HOST/sample.pdf\"}"

-i is what makes this test meaningful: the response body is empty, so the headers are the entire result. Swap prebuilt-layout for prebuilt-read, prebuilt-invoice, or a custom model id to confirm the wildcard covers them all.

To send bytes from disk instead of a URL, post the file with its own content type:

curl -i -X POST "https://YOUR-APIM-HOST.azure-api.net/mydocintel/documentintelligence/documentModels/prebuilt-read:analyze?api-version=2024-11-30" ^
  -H "api-key: YOUR-APIM-SUBSCRIPTION-KEY" ^
  -H "Content-Type: application/pdf" ^
  --data-binary "@sample.pdf"

GET — poll for the result

Call the Operation-Location value returned by the POST, with the same subscription key:

curl "https://YOUR-APIM-HOST.azure-api.net/mydocintel/documentintelligence/documentModels/prebuilt-layout/analyzeResults/RESULT-ID?api-version=2024-11-30" ^
  -H "api-key: YOUR-APIM-SUBSCRIPTION-KEY"

Two passing calls confirm the whole chain: the operations match, the subscription key is accepted, the resource key is injected, the wildcard forwards the path and query string intact, and the outbound rewrite keeps the client on the gateway.

Client configuration

Point the client at the gateway rather than at the resource. Three things must be correct:

In the Akumina AI settings (Settings › AI Settings), the AzureDocumentIntelligence block configured under Configure the Embeddings section in Akumina AI settings changes in two ways: Endpoint becomes the gateway base URL, and an AdditionalHeaders entry carries the APIM subscription key under the header name the API expects — the same mechanism the Foundry endpoint uses:

"AzureDocumentIntelligence": {
    "Enabled": true,
    "Extensions": [ "png", "jpeg", "jpg", "xlsx" ],
    "ApiKey": "<APIM_SUBSCRIPTION_KEY — not the resource key>",
    "Endpoint": "https://<apim-host>.azure-api.net/mydocintel",
    "AdditionalHeaders": {
        "api-key": "<APIM_SUBSCRIPTION_KEY>"
    }
}

Include AdditionalHeaders only when the endpoint is fronted by a gateway; a direct connection needs ApiKey and Endpoint alone. The header name must match the Subscription header name on the API’s Settings tab. ApiKey should no longer carry the Document Intelligence resource key — that key now lives only in the gateway’s named value, and whatever the client sends in that header is overridden by the inbound policy. Because the wildcard passes the service’s own route forms through unchanged, a client written against the official Document Intelligence SDK works against this gateway with only its endpoint and credential changed.

Troubleshooting

Enable the APIM trace first — the Test blade does this automatically — and replay the request. It shows whether an operation matched and prints the exact outbound URL sent to the resource, which resolves most of these in one look.

Security notes