Create A Data Access Request From A Template

This guide shows how to use the request template and request APIs to create a reusable access template and then use it to spin up a new request environment.

Use this page for the flow. Use the API Reference for the exact contract of each endpoint.

Endpoints Used

In a full approval flow, an admin also approves the request before activation:

POST /v1/admin/requests/{id}/approve

Flow Overview

The normal sequence is:

Create a reusable request template.
Store the returned template ID.
Create a data access request that references that template.
Wait for the request to be approved.
Activate the approved request.
Create a tunnel for the active request if inbound access is needed.
Use the returned request environment for queries, explorer access, or tunnel-backed API access.

Step 1: Create The Request Template

Request templates use the RequestTemplateInput schema. The required fields are:

name
title
description
business_justification
risk_level
validity_period
scope

The scope field is an array of datasource selections using ContractDatasourceInput.

Example:

{
  "name": "customer-support-template",
  "title": "Customer support investigation",
  "description": "Scoped support access to account and billing data",
  "business_justification": "Allows support engineers to investigate customer-reported issues",
  "risk_level": "medium",
  "validity_period": "1d",
  "scope": [
    {
      "datasource": "production-postgres",
      "datasets": [
        {
          "target_location": "public.accounts",
          "target_name": "accounts",
          "columns": ["id", "email", "status", "created_at"]
        },
        {
          "target_location": "public.billing_events",
          "target_name": "billing_events",
          "columns": ["account_id", "event_type", "amount", "created_at"]
        }
      ]
    }
  ]
}

Submit it with POST /v1/request-templates.

The response returns the created template, including its id.

Step 2: Reuse The Template To Create A Request

Create the actual data access request with POST /v1/requests.

The request body uses CreateRequestInput. To create a request from an existing template, include:

request_template_id
business_justification
description
risk_level
scope

You can also provide:

title
source
external_ticket_id
external_ticket_url
valid_until

Example:

{
  "request_template_id": "tmpl_123456",
  "title": "Support request for account review",
  "description": "Investigate billing mismatch reported by customer",
  "business_justification": "Customer support needs temporary access to investigate a production issue",
  "risk_level": "medium",
  "source": "manual",
  "scope": [
    {
      "datasource": "production-postgres",
      "datasets": [
        {
          "target_location": "public.accounts",
          "target_name": "accounts",
          "columns": ["id", "email", "status", "created_at"]
        },
        {
          "target_location": "public.billing_events",
          "target_name": "billing_events",
          "columns": ["account_id", "event_type", "amount", "created_at"]
        }
      ]
    }
  ]
}

In practice, keep the request scope aligned with the template you are reusing. The returned request object includes the new request id, status, and later the environment_id and environment_status once the request is activated.

Step 3: Wait For Approval

After creation, check the request with GET /v1/requests/{id}.

The request must be approved before it can be activated into a live environment. In an admin-driven workflow, approval is handled through POST /v1/admin/requests/{id}/approve.

Once approved, the request status moves to approved.

Step 4: Activate The Request And Provision The Environment

Activate the approved request with POST /v1/requests/{id}/activate.

This is the step that spins up the request environment. The response returns the updated request object, which can include:

environment_id
environment_status
status
scope

After activation, the request becomes the backing object for the provisioned environment and its approved data scope.

Example response:

{
  "success": true,
  "data": {
    "id": "req_123456",
    "status": "active",
    "title": "Support request for account review",
    "environment_id": "env_7890",
    "environment_status": "running",
    "valid_until": "2026-03-24T17:00:00Z",
    "request_template": {
      "id": "tmpl_123456",
      "name": "customer-support-template"
    }
  }
}

Step 5: Inspect The Activated Request

Use GET /v1/requests/{id} to confirm the request is now active and tied to an environment.

The important response fields are:

id
status
environment_id
environment_status
request_template
valid_until

At that point, the environment is ready for the next step in the workflow, such as:

request queries
explorer access
tunnel creation

Step 6: Create A Data Tunnel

Once the request is active, create a tunnel with POST /v1/requests/{id}/tunnel.

That endpoint creates a request-scoped tunnel for the active environment and returns the tunnel details. After creation, retrieve the current tunnel state with GET /v1/requests/{id}/tunnel.

The returned tunnel object can include URLs such as:

the edge URL
the explorer URL
the API URL

This gives the request an inbound access surface after activation, without changing the approved scope of the request.

Example response:

{
  "success": true,
  "data": {
    "id": "tun_123456",
    "provider": "cloudflare",
    "status": "ready",
    "public_url": "https://example.trycloudflare.com",
    "edge_url": "https://a10e.company.com/v1/tunnels/tun_123456/edge",
    "explorer_url": "https://a10e.company.com/v1/tunnels/tun_123456/edge/explorer",
    "api_url": "https://a10e.company.com/v1/tunnels/tun_123456/edge/api",
    "sidecar_name": "a10e-env-7890-tunnel",
    "credentials": [
      {
        "type": "api_key"
      },
      {
        "type": "basic_auth",
        "username": "tunnel"
      }
    ]
  }
}

The critical fields to capture from the tunnel response are:

status, to confirm the tunnel is usable
explorer_url, for web-based access
api_url, for API-based access
credentials, for authenticating tunnel entry

The usual sequence is:

activate the approved request
create the tunnel
read the tunnel details
use the explorer or API endpoint exposed by that tunnel

Notes On Scope

Both templates and requests use the same scope model built from ContractDatasourceInput. That means:

the template defines the reusable approved shape
the request instantiates that shape for a specific access event
activation provisions the environment for the request’s scoped data access