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

# Applications and Personas

> Keep integration identity separate from delivery policy

Applications and Personas serve different purposes. You can use either without registering the other.

| | Application | Persona |
| - | - | - |
| Identifies | An optional integration named by `application_id` | A collective or policy name selected in the recipient address |
| Controlled by | Its control DID | Its operator DID |
| Policy role | Triggers separate control actions | Sets recipient delivery requirements and routes |
| DNS needed | Only when the Application claims a domain for `Call` | Only when the Persona name is a domain |

An Application record contains an ID, control DID, status, and revision. It can also have a separately verified domain and DIDs that have agreed to receive its control messages. It contains no manifest and does not select the recipient or change the encrypted payload.

An envelope may carry both `application_id` and `tag`. They are independent: `application_id` selects the Application policy; `tag` is an optional message label that a rule may match. The recipient DID or Persona policy still determines delivery. An applicable Application policy runs alongside it.

For example, an Application policy can ask a Cache to `Send` a small control message to its control DID after storage. The receiving service decides whether to send a push notification. The original envelope stays encrypted and unchanged.

## Domain and target limits

Without a verified domain, an Application can `Send` only to its control DID or a DID explicitly linked by both DID owners. With a verified domain, it can also `Call` an advertised HTTPS service on that exact domain. Domain control uses the existing DNS challenge for a domain-shaped Persona owned by the same control DID. The Persona supplies DNS proof; its identity and policy remain separate from the Application.

If a target or DNS proof is no longer valid, the control action fails without delaying the original delivery.

## Register an Application through the Directory

Send your control DID and its signing key ID to [prepare Application registration](/api-reference/directory/applications/prepare-registration). Sign the returned `canonical_payload` bytes with that DID key, then [submit registration](/api-reference/directory/applications/register) with the same fields, returned `nonce` and `canonical_payload`, and your Base64 signature. A `202` response means the transaction was submitted. Check `GET /applications/{applicationId}` for finalized registration before publishing its policy.

The control DID can already be used as the `Send` target. To add another target, [prepare an authorization](/api-reference/directory/applications/prepare-authorization) with `set_linked_did`; both the control DID and linked DID sign the returned payload before you [submit it](/api-reference/directory/applications/authorize). To use `Call`, first verify the domain through a domain-shaped Persona controlled by the same DID, then submit a `set_domain` intent through those endpoints with the control DID's signature.

These routes are included in the deployed spec 123 Java services. An Application record or policy exists only after its own transaction is finalized; deployment does not register one automatically.

See [shared policies](/concepts/policy-v3) for rule details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.