Skip to main content

Per-request keys

A per-request key is a short-lived credential that DIAL Core generates for a single request to an application or model adapter. It is valid only for the lifetime of that request. Per-request keys govern an application's access to user files, attribute cost and usage limits to the request originator, carry OpenTelemetry tracing context, and mediate access for external applications reached through routes.

This page is a reference for how per-request keys behave. It is intended for developers building applications, adapters, or Toolsets that DIAL Core invokes.

Request types​

DIAL Core distinguishes two kinds of request when issuing keys.

TermDefinitionExample
Root requestThe initial request DIAL Core receives from DIAL Chat or another client.DIAL Chat → DIAL Core
Non-root requestA request DIAL Core makes to fulfil the root request.DIAL Chat → DIAL Core → Application A → DIAL Core → Application B

Key lifecycle​

Root request​

  1. DIAL Core verifies that the caller — a chat user or an application — has the permissions and limits required by the access control configuration, then generates a per-request key for the request.
  2. DIAL Core stores data associated with the key in memory or in Redis. This data may include the user's JWT or the application's API key, the trace-id, the core-parent-span-id, and the list of user files attached to the request.
  3. DIAL Core passes the key to the application or model adapter in the Api-Key header. The application or adapter returns the same key in the Api-Key header when it calls DIAL Core for model requests or file storage operations.
  4. DIAL Core invalidates the key when the request completes.

Non-root request​

  1. DIAL Core verifies that the incoming per-request key — the one issued for the root request — is valid and known.
  2. DIAL Core checks the caller's permissions, then generates and stores a new outgoing key. This key carries all data from the parent request plus the data needed for the current request.
  3. DIAL Core passes the new outgoing key in the request header. The application or adapter returns it in the Api-Key header when calling DIAL Core.
  4. DIAL Core invalidates the outgoing key when the request completes.

Associated data​

Each key is linked to data used to enforce access, attribute cost, and record telemetry.

FieldPurpose
JWT or API keyIdentifies the request originator for permission and limit checks.
trace-idAttributes cost, usage limits, and statistics to the originating request.
core-parent-span-idCorrelates spans when gathering statistics.
Attached user filesThe set of files the application is permitted to access during the request.

Cost and limit attribution​

DIAL Core attributes the cost and usage limits of a model call to the user or application that initiated the request. Include traceparent in the request header so that the trace-id is preserved across the request lifetime in memory or in Redis.

Statistics​

DIAL Core computes statistics from the trace-id and core-parent-span-id stored in the data linked to the key.

File access​

DIAL Core verifies the originator's permissions and limits using the JWT or API key from the root request, then links the request's user files to the per-request key. Throughout the key's lifetime and across the call stack, DIAL Core uses this linked data to determine the application's access rights. If an application attempts to share a file that is neither in the linked list nor directly accessible to it, the request fails with 403 Forbidden.

To let an application write output files for the user, DIAL Core grants the application full access to a designated output folder in the user's bucket.

appdata in the bucket response​

The path of the output folder is returned in the appdata field of the GET /v1/bucket response. When the request is made with a per-request key, appdata contains the path to the shared folder, including the user's bucket and the application's deployment-id as registered in the DIAL Core configuration.

{
  "bucket": "{application-bucket-id}",
  "appdata": "{user-bucket-id}/appdata/{deployment-id}"
}

Telemetry tracing​

For OpenTelemetry tracing, include traceparent in the request header. Tracing does not affect limits, statistics, or file sharing.

Routes for external applications​

Applications can communicate through routes — endpoints registered in DIAL Core that need not conform to the Unified API. A route bridges DIAL Core and an external application: DIAL Core acts as an intermediary, handling authentication and authorization between the client and the external endpoint.

External applications have no direct access to DIAL resources, but they may need to read user data or call other applications and models in DIAL. Per-request keys issued for routes enable:

  • Access to language models and applications.
  • A dedicated workspace in the BLOB store, where the route can read and write files under /Keys/<route_name>/.
  • The ability to fetch user information through the /v1/user/info endpoint.

Access and cost control for routes​

Assign roles to a route to control access and limits. In the following configuration, the route myApp requires the app_user role, and a user with that role may call the route up to 1000 times per minute:

{
  "routes": {
    "myApp": {
      "userRoles": ["app_user"]
    }
  },
  "roles": {
    "app_user": {
      "limits": {
        "myApp": {
          "requestsPerMin": "1000"
        }
      }
    }
  }
}

For the full schema, see routes configuration and roles configuration.

Example​

A DIAL Chat user asks an external RAG application to answer a prompt based on an attached file:

  1. DIAL Chat uses a route to reach the external RAG application. DIAL Core generates a per-request key for the interaction.
  2. The RAG application uses the key to call a language model in DIAL, which processes the file and generates a response.
  3. The response is relayed back to the user in DIAL Chat, completing the request.

Access to models and request limits are determined by the roles assigned to both the route and the user in DIAL Core.

Further reading​