---
slug: vta/did-templates/get
version: "3.1"
title: VTA DID-Template — Get
summary: An authenticated caller fetches one DID template by name — global when contextId is absent, context-scoped when present.
status: draft
targetFrameworkVersion: "0.5.0"
category: did-management
keywords:
  - vta
  - did-template
  - did
  - provisioning
  - get
  - context
authors:
  - Glenn Gore (https://github.com/stormer78)
parties:
  - role: Authenticated caller
    requirement: REQUIRED
    member: issuer
  - role: VTA
    requirement: REQUIRED
    member: recipient
proofRequirement:
  requirement: RECOMMENDED
  rationale: Fetching a template is a pure read that discloses only non-secret provisioning metadata and changes nothing. The transport-level session that authenticates the caller (plus context access when contextId is present) is sufficient to authorize it; a producer proof adds a transport-independent identity for the VTA's audit trail, so it is RECOMMENDED rather than REQUIRED. The blanket REQUIRED of 1.0 was re-derived per task for 2.0 — mutations keep REQUIRED, pure reads do not.
sideEffects:
  level: none
  rationale: "Read-only read of a DID template in the selected scope."
subjectPath: /name
exposure:
  discloses: metadata
  actsAsSubject: false
errorCodes:
  - code: vta/did-templates/get:notFound
    meaning: No template with this name in the selected scope.
    retryable: false
related:
  - vta/did-templates/list
  - vta/did-templates/create
  - vta/did-templates/update
  - vta/did-templates/delete
  - vta/did-templates/render
---

## Abstract

The **VTA DID-Template — Get** Trust Task fetches one DID template by name from **one scope** on a Verifiable Trust Agent. A *DID template* is the JSON shape of a DID document with `{TOKEN}` placeholders plus the variable contract the VTA's renderer enforces; the VTA fills the placeholders with keys it mints and caller-supplied variables when provisioning an integration.

The scope is selected by the **optional `contextId`** field:

* **Absent** — the **global** scope: templates visible to every context on the VTA. Any authenticated caller may read them.
* **Present** — that **context's** scope: templates visible within a single context. The caller must have access to the context.

Version 2.0 merges the 1.0 pair [`vta/did-templates/get/1.0`](../1.0/spec.md) and [`vta/contexts/did-templates/get/1.0`](../../../contexts/did-templates/get/1.0/spec.md) into this single task; the per-scope authorization moved from the slug structure to the `contextId` field.

## Status of this Document

This is a **draft** *Trust Task specification* per [SPEC.md §5.3](/SPEC.md#53-maturity-levels); the schema **MAY** change without notice. Feedback via the [issue tracker](https://github.com/trustoverip/dtgwg-trust-tasks-tf/issues).

## Changes from 3.0

The two provenance instants of the returned `DidTemplateRecord` change type:

* **`createdAt`**: integer Unix seconds → RFC 3339 string (`type: "string"`, `format: "date-time"`), e.g. `1785315601` → `"2026-07-29T09:00:01Z"`.
* **`updatedAt`**: integer Unix seconds → RFC 3339 string, likewise.

Both members keep their names and remain REQUIRED. The registry-wide convention is that every instant on the wire is an RFC 3339 string in a member named `*At`; these two were the remaining integer instants in the shared template record.

The change arrives through the shared component: this version re-pins every `$ref` into `did-template.schema.json` (`DidTemplate` and `DidTemplateRecord`) from `vta/_shared/0.2` to `vta/_shared/0.7`. `DidTemplate`, `Scope` and every other member of the record are unchanged. The request payload is unchanged.

Breaking on the wire, released as a `MINOR` increment under [§5.2](/SPEC.md#52-compatibility-rules)'s `draft` allowance. `3.0` remains published and pinned to `vta/_shared/0.2`.

## Conformance

[[RFC2119]](https://www.rfc-editor.org/rfc/rfc2119) and [[RFC8174]](https://www.rfc-editor.org/rfc/rfc8174) key-word conventions apply.

A conforming **producer** (the authenticated caller) **MUST**:

1. Emit a *Trust Task document* whose `type` is `https://trusttasks.org/spec/vta/did-templates/get/3.1`, with itself as `issuer` and the VTA as `recipient`.
2. Populate `payload.name` with the template name to fetch, and `payload.contextId` with the target context — or omit `contextId` to read from the global scope.

A conforming producer **SHOULD** include a `proof` member per [SPEC.md §4.7](/SPEC.md#47-proof) so the read is attributable independent of transport.

A conforming **consumer** (the VTA) **MUST**:

1. Validate the document per [SPEC.md §7.2](/SPEC.md#72-consumer-requirements) and verify the `proof` when present.
2. Where the producer is not an authenticated caller — or, when `payload.contextId` is present, lacks access to that context — respond with the framework's `permissionDenied` ([SPEC.md §8.3](/SPEC.md#83-standard-error-codes)).
3. Where no template named `payload.name` exists in the selected scope, respond with `vta/did-templates/get:notFound`.
4. On success, return the stored [DidTemplateRecord](#response).

## Definitions

* **Authenticated caller.** The party invoking the task; identified by `issuer`. Any caller the VTA can authenticate; access to `payload.contextId` is additionally required when it is present.
* **VTA.** The Verifiable Trust Agent that stores and renders templates; identified by `recipient`.
* **DidTemplateRecord.** A stored template plus provenance (scope, timestamps, creator DID) — see the [shared definition](../../../_shared/0.7/did-template.schema.json).

## Request

A *request* document carries `type: https://trusttasks.org/spec/vta/did-templates/get/3.1` with a payload that validates against the top-level schema in `payload.schema.json`.

### Fetch a context-scoped template

```json
{
  "id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "type": "https://trusttasks.org/spec/vta/did-templates/get/3.1",
  "issuer": "did:web:admin.example",
  "recipient": "did:web:vta.example",
  "issuedAt": "2026-07-29T09:00:00Z",
  "payload": {
    "contextId": "primary",
    "name": "messaging-bridge"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "verificationMethod": "did:web:admin.example#key-1",
    "created": "2026-07-29T09:00:00Z",
    "proofPurpose": "authentication",
    "proofValue": "z3kg..."
  }
}
```

Omit `contextId` to fetch the global template of the same name instead.

## Response

A success *response* document carries `type: https://trusttasks.org/spec/vta/did-templates/get/3.1#response`, with a payload that validates against the `$anchor: "response"` sub-schema in `payload.schema.json`. The response payload is the persisted **DidTemplateRecord**.

Failures use `trust-task-error` ([SPEC.md §8](/SPEC.md#8-error-responses)), not the `#response` variant — including `vta/did-templates/get:notFound`.

### The stored record

Response to the request example. The resolved `scope` names where the record lives:

```json
{
  "id": "1b2c3d4e-5f60-7182-93a4-b5c6d7e8f9a0",
  "type": "https://trusttasks.org/spec/vta/did-templates/get/3.1#response",
  "threadId": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "issuer": "did:web:vta.example",
  "recipient": "did:web:admin.example",
  "issuedAt": "2026-07-29T09:00:01Z",
  "payload": {
    "schemaVersion": 1,
    "name": "messaging-bridge",
    "kind": "messaging-bridge",
    "description": "DIDComm messaging bridge host.",
    "methods": ["webvh", "web"],
    "requiredVars": ["MEDIATOR_DID"],
    "optionalVars": { "ACCEPT": ["didcomm/v2"] },
    "defaults": { "preRotationCount": 2 },
    "document": {
      "id": "{DID}",
      "verificationMethod": [
        {
          "id": "{DID}#{SIGNING_KEY_MB}",
          "type": "Multikey",
          "controller": "{DID}",
          "publicKeyMultibase": "{SIGNING_KEY_MB}"
        }
      ],
      "service": [
        {
          "id": "{DID}#didcomm",
          "type": "DIDCommMessaging",
          "serviceEndpoint": { "uri": "{MEDIATOR_DID}", "accept": "{ACCEPT}" }
        }
      ]
    },
    "scope": { "type": "context", "contextId": "primary" },
    "createdAt": "2026-07-29T09:00:01Z",
    "updatedAt": "2026-07-29T09:00:01Z",
    "createdBy": "did:web:admin.example"
  }
}
```

## Security & Privacy

**Scope selection is authorization, not filtering.** The `contextId` field selects which scope is read, and the VTA authorizes against it server-side: the global scope is open to any authenticated caller, a context scope only to callers with access to that context. Lack of access yields `permissionDenied` — never `notFound` — so the error does not leak whether a template of that name exists in a context the caller cannot see.

**Attributed read, proportionate proof.** Fetching a template discloses only non-secret provisioning metadata, so the producer `proof` is **RECOMMENDED** rather than REQUIRED: the transport session already authorizes the read, and the proof's value here is a transport-independent identity for the VTA's audit trail. Deployments that require attributable reads SHOULD reject unproven requests as a matter of local policy.

**Templates are shapes, not secrets.** A template contains only placeholder tokens and public document structure — never key material. The VTA mints all keys at render time; a template never carries a private key. Even so, the optional `ext` extension (see [SPEC.md §4.5.1](/SPEC.md#451-the-ext-extension-member)) is signed alongside the rest of the payload when a proof is present, so producers **MUST NOT** place data in `ext` they would not be comfortable signing.

### Data carried

The response carries stored templates — placeholder tokens and public document
structure, never key material.

The `keys` block makes a read **a disclosure of cryptographic posture**: the
response says, for every template in scope, whether the DIDs minted from it are
classical or post-quantum. A reader who can list templates learns the shape of
the deployment's migration, which is a more concentrated view than resolving DID
documents one at a time. The authorization gate is therefore the whole of the
protection here; there is no minimisation available in the payload, because a
template with its `keys` block elided would not be a usable answer.

### Correlation

The recipient learns which operator is reading and when. A poll correlates to one
operator by `issuer` and publishes its cadence to anyone watching the channel;
request and response correlate by `threadId`.

The returned provenance — creator DID and timestamps — correlates each template to
the operator who wrote it, so a read discloses not only the current shape but who
shaped it.

### Retention

Caller-side. A consumer **SHOULD** treat a fetched template as a cache of the
recipient's record rather than a copy of record, and **SHOULD NOT** persist it
beyond the operation that needed it — a stale template read back later describes
a shape the VTA may no longer mint, and acting on one is how a caller provisions
against a configuration that no longer exists.

### Consent/purpose

An administrative read by an operator the ACL already authorizes, scoped to the
templates that operator may see. **No subject data is involved and no consent
ceremony applies.** The purpose is bounded by the same scope as the write: a
context administrator sees that context's templates, not the global scope.
