Long-running operations

Status: convention only. No DiligenceID operation is asynchronous today.

Every Management and Product operation currently completes within its own request. Nothing returns 202 Accepted, and there is no operation resource to poll. This page exists so that when the first genuinely long-running operation ships, it uses a shape clients have already been told about — and so that nobody builds a second, different one.

If you are integrating today, you do not need anything on this page.

Why this is written down before it is needed

Asynchronous operations tend to arrive one at a time, each inventing its own polling shape, and a client ends up handling three conventions for what is conceptually one thing. Agreeing the shape while there is nothing to migrate costs nothing; agreeing it afterwards means changing published contracts.

The alternative — making an operation asynchronous now so this page can describe something real — would be worse. A synchronous operation dressed as an asynchronous one still takes exactly as long, and every caller pays for a polling loop that never had anything to wait for.

The convention

An operation that cannot complete within a request responds:

HTTP/1.1 202 Accepted
Operation-Location: https://api.example.diligence.id/management/operations/{operationId}?api-version=2026-08-30
Retry-After: 5
x-ms-request-id: req_5f2c...

Operation-Location is an absolute URL. Treat it as opaque and do not construct it yourself — its shape is free to change, and the whole point of returning it is that you do not have to know.

Retry-After is in seconds, and it is guidance from the service about how long the work usually takes. Polling faster will not make it finish sooner and will spend your rate limit.

The operation resource

GET the Operation-Location URL:

{
  "id": "op_9c1e4b7a",
  "status": "Running",
  "createdAt": "2026-08-30T04:11:02Z",
  "lastUpdatedAt": "2026-08-30T04:11:37Z",
  "error": null
}

Running is the only non-terminal state. Once an operation reaches any other, it will not change again.

When status is Failed, error carries the standard error object — the same code, message, target and innerError you would have received had the operation been synchronous. There is no second error vocabulary to learn.

Polling

1. Submit the request.
2. If the response is 200 or 201, you are done — this operation is synchronous.
3. If it is 202, read Operation-Location and Retry-After.
4. Wait Retry-After seconds. GET Operation-Location.
5. Repeat from 4 while status is "Running".
6. On Succeeded, re-read the resource if you need its new state.
   On Failed, handle error exactly as you would a synchronous error.

Write step 2 as a real branch even though nothing returns 202 today. It is three lines now and a redeployment later.

Set your own overall timeout. An operation that stays Running far past its Retry-After guidance is worth raising with support, quoting the x-ms-request-id from the original 202.

What this is likely to be used for

Work that depends on something outside DiligenceID's own database and cannot be made fast by making DiligenceID faster:

• dedicated tenant provisioning
• custom domain provisioning and certificate issuance
• onboarding or offboarding an external identity provider
• rotating a signing key held in an external key store

Note what is absent: issuing a credential, running a verification and revoking are all synchronous and are expected to stay that way. They are on the critical path of somebody's actual transaction, and moving them behind a polling loop would make every integration harder in exchange for nothing.

Related

• Errors — the error object an operation reports on failure
• Idempotency — safely retrying the submission itself
• OpenAPI — the canonical contracts