> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acreblitz.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> State which API version you are using. V1 uses https://esa.acreblitz.com/api/v1; V2 uses https://esa-v2.acreblitz.com/api/v2.
> Read /llms.txt for links to both versions. For V2 bulk integration, read bulk submission, status, results, and /v2/errors before constructing requests.

# Issue portal access

> Issue an expiring portal link for one application

Issue an expiring portal link for one application.

## Request

<ParamField path="application_event_id" type="string" required>
  Opaque application-event reference returned by an ESA check.
</ParamField>

<ParamField body="ttl_seconds" type="integer">
  Link lifetime, 60–86,400 seconds. Defaults to your configured lifetime (one hour by default).
</ParamField>

<ParamField body="return_url" type="string">
  Optional absolute HTTP(S) URL used to return the user when this link is rejected as expired; maximum 2,000 characters.
</ParamField>

## Response and access

Returns an expiring `portal_url`, `expires_at`, `application_event_id`, `provider_group_id`, and the provider's `portal_access_mode`. Treat the URL as an opaque credential and use it unchanged. Do not derive or parse its token format.

This endpoint issues a signed expiring link in either access mode. In signed-link mode, the normal ESA-check response already provides an expiring `mitigation_portal_url`; an extra call is often unnecessary. In token mode, this endpoint lets you issue a short-lived link without changing your provider's default access mode.

The application must belong to your provider and its portal must be available. A grouped application link also supports navigation between applications in its job group. A portal lock prevents mitigation writes but does not prevent reading the portal.

The example shows selected response fields. Its placeholder URL represents the complete URL returned by the service.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST 'https://esa-v2.acreblitz.com/api/v2/applications/019953f8-8c00-7000-8000-000000000002/portal-access' \
    --header "X-API-Key: $ACREBLITZ_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
    "ttl_seconds": 3600,
    "return_url": "https://partner.example/applications/north"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — selected response fields theme={null}
  {
    "success": true,
    "application_event_id": "019953f8-8c00-7000-8000-000000000002",
    "provider_group_id": "work-order-42",
    "portal_url": "https://acreblitz.com/esaportal/field?t=opaque-returned-credential",
    "expires_at": "2026-10-05T15:00:00.000Z",
    "portal_access_mode": "token"
  }
  ```
</ResponseExample>

## Errors

Endpoint-specific errors are `404 APPLICATION_NOT_FOUND`, `403 INVALID_TOKEN`, `INACTIVE_TOKEN`, or `PORTAL_EXPIRED`, and `503 PORTAL_SAS_UNCONFIGURED`. Portal access denials refer to the field’s availability, not your API key.

All routes can also return [authentication, validation, rate-limit, and dependency errors](/v2/errors#http-error-catalog). Use the [error catalog and examples](/v2/errors) to choose a retry or correction. Keep `X-Request-ID` when present.