Connection Authority

Connection Authority lets an administrator define where an integration may connect and what it may do. For example, a runner can be allowed to check one GitLab project without receiving a credential for every project. The connection record refers to a secret kept in Secrets Storage; it does not contain the password or token itself.

Each saved change creates a new revision. A revision records the allowed target, operation IDs and secret versions. Use the current revision when probing, updating or revoking the connection, so an old request cannot silently replace a newer setting.

What a connection can do

Check the supported operations before using a connection in a workflow.

A connection can store allowed operations and probe its target:

• Stores and versions the authority. Every advance is an immutable revision with a digest; the previous revision stops being current.
• Publishes the credential-free references. When a plugin runtime task is admitted, the runner receives the exact secret and connection revisions the task may use — never plaintext — and the runner boundary re-validates that authority on both dispatch paths. A task whose authority cannot be validated is refused.
• Answers resolution exactly. Reading the current revision returns it, or nothing when the connection was revoked.
• Runs the probe operation. An operation named <adapter>.probe (for example gitlab.probe) asks an HTTP or HTTPS target inside the connection’s targetPolicy whether it answers and whether it accepts the connection’s credential. Mockarty uses the secret on the server side and returns only the outcome — succeeded, or failed when the target refused the credential, answered with an error or could not be reached. The probe changes nothing at the target, and the secret never appears in the response.
• Sends requests as the connection’s account. <adapter>.target_read sends one GET, HEAD or OPTIONS request and <adapter>.target_write one POST, PUT, PATCH or DELETE request to the connection’s own target, with the connection’s credential added on the server. You choose the path (under a pathPrefixes entry), the method (listed in methods), query parameters, extra headers and a body; the host, port and scheme always come from the target policy. The answer — status, safe headers and up to 64 KiB of body — is returned once. Anything in it that equals the credential is replaced with [redacted]; Set-Cookie is never returned. This is how an autonomous mission tests as a restricted account.

Operation IDs use the form <adapter>.<class>. Allowed classes are probe, target_read, target_write, issue_ephemeral_token, rotate and revoke. probe, target_read and target_write can be executed. Requests to execute issue_ephemeral_token, rotate or revoke return 422 without changing the target. These names can appear in a descriptor, but listing them does not enable their execution.

What a target request records

Every executed operation leaves a receipt with its outcome. For target requests the receipt also names why a request was refused, in result.evidence:

A write whose outcome is unknown is never reported as “not applied”. Repeating the same idempotencyKey returns the recorded receipt without sending the request again.

Before you start

1. Put each credential in Secrets Storage.
2. Note the secret store ID, key, and positive version number.
3. Define an exact target allowlist: scheme, host, port, path prefix, and provider resource where applicable.
4. Choose the operation IDs the connection may execute, spelled <adapter>.<class> (for example gitlab.probe). For target requests also list the allowed HTTP methods in the target policy.

An Owner or Admin can create, advance, and revoke descriptors. Users and Viewers can inspect them but cannot change connection authority.

Descriptor example

Save this as gitlab-connection.json. The create endpoint assigns the namespace and revision; do not put raw credentials in this file.

{
  "contractVersion": "mockarty.connection/v1",
  "id": "gitlab-prod",
  "kind": "gitlab",
  "endpoint": "https://gitlab.example.com/api/v4",
  "residency": "customer_contour",
  "configuredBindings": {
    "project": "payments/service"
  },
  "targetPolicy": {
    "schemes": ["https"],
    "hosts": ["gitlab.example.com"],
    "ports": [443],
    "pathPrefixes": ["/api/v4"],
    "projects": ["payments/service"]
  },
  "secretRefs": [
    {"storeId": "team-vault", "key": "gitlab-token", "version": 3}
  ],
  "allowedOperationIds": ["gitlab.probe"],
  "dataClasses": ["source_code"],
  "settingsSchema": {"type": "object"}
}

The returned snapshot contains the complete descriptor, its revision, and a digest. Keep the revision for the next advance or revoke operation.

Admin UI

Open Administration → Integrations → Connection Authority. Select a concrete namespace, paste a credential-free descriptor, then use Create, Load, Advance, Probe, or Revoke. Advance, probe and revoke require the exact current revision; a stale revision is rejected instead of overwriting a concurrent change. Probe uses the descriptor’s first <adapter>.probe operation and aims it at the descriptor’s endpoint.

A failed probe needs interpretation: HTTP 401 means the target rejected authentication, so the credential or its validity needs checking; HTTP 403 means the target refused the requested read, while HTTP 5xx means the target failed. A redirect also fails the probe because it cannot prove that the credential was accepted; Mockarty does not follow it or forward the credential. These responses do not by themselves prove that the target authenticated a particular principal or forbids a write action. A probe only performs GET or HEAD.

REST API

curl -X POST "$MOCKARTY_URL/api/v1/namespaces/payments/connections" \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @gitlab-connection.json

curl -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/payments/connections/gitlab-prod"

curl -X PUT "$MOCKARTY_URL/api/v1/namespaces/payments/connections/gitlab-prod?expectedRevision=1" \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @gitlab-connection.json

curl -X DELETE \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/payments/connections/gitlab-prod?revision=2"

Probe revision 2 of the connection. The target must sit inside its targetPolicy; reuse idempotencyKey to make a retry return the recorded outcome instead of probing again:

curl -X POST "$MOCKARTY_URL/api/v1/namespaces/payments/connections/gitlab-prod/execute" \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"revision":2,"operationId":"gitlab.probe","idempotencyKey":"probe-2026-09-26",
       "target":{"scheme":"https","host":"gitlab.example.com","port":443,"path":"/api/v4"}}'

The answer carries result.status (succeeded or failed) and a receiptId; it never contains the credential. A GitLab token is sent as PRIVATE-TOKEN when the descriptor sets "configuredBindings": {"probe.header_style": "gitlab"}; the default is Authorization: Bearer, and "api-gateway" sends X-API-Key. The same setting applies to target requests.

Create an item as the connection’s account. Put the request details in arguments:

curl -X POST "$MOCKARTY_URL/api/v1/namespaces/payments/connections/shop-reader/execute" \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"revision":1,"operationId":"shop.target_write",
       "target":{"scheme":"https","host":"shop.example.com","port":443,"path":"/api/items","method":"POST"},
       "arguments":{"body":"{\"name\":\"test item\"}","headers":{"Accept":"application/json"}}}'

A read-only account gets result.evidence: "permission_denied" and, in response, the target’s own answer (statusCode: 403 and its message). response is present only on the call that actually sent the request.

SDKs

Go

descriptor := mockarty.ConnectionDescriptor{
    ContractVersion: "mockarty.connection/v1",
    Namespace: "payments", ID: "gitlab-prod", Kind: "gitlab",
    Endpoint: "https://gitlab.example.com/api/v4",
    TargetPolicy: mockarty.ConnectionTargetPolicy{
        Schemes: []string{"https"}, Hosts: []string{"gitlab.example.com"},
        Ports: []uint16{443}, PathPrefixes: []string{"/api/v4"},
        Projects: []string{"payments/service"},
    },
    SecretRefs: []mockarty.ConnectionSecretRef{{StoreID: "team-vault", Key: "gitlab-token", Version: 3}},
    AllowedOperationIDs: []string{"gitlab.probe"},
}
snapshot, err := client.Connections().Create(ctx, descriptor)

Use GetCurrent, Advance, and Revoke on client.Connections() for the remaining lifecycle operations.

Python

descriptor = {
    "namespace": "payments",
    "contractVersion": "mockarty.connection/v1",
    "id": "gitlab-prod",
    "kind": "gitlab",
    "endpoint": "https://gitlab.example.com/api/v4",
    "targetPolicy": {"schemes": ["https"], "hosts": ["gitlab.example.com"], "ports": [443], "pathPrefixes": ["/api/v4"]},
    "secretRefs": [{"storeId": "team-vault", "key": "gitlab-token", "version": 3}],
    "allowedOperationIds": ["gitlab.probe"],
}
snapshot = client.connections.create(descriptor)

Use get_current, advance, and revoke on client.connections. The async client exposes the same methods.

Java

ObjectNode descriptor = mapper.createObjectNode();
descriptor.put("namespace", "payments");
descriptor.put("contractVersion", "mockarty.connection/v1");
descriptor.put("id", "gitlab-prod");
descriptor.put("kind", "gitlab");
descriptor.put("endpoint", "https://gitlab.example.com/api/v4");
// Add targetPolicy, exact secretRefs, and allowedOperationIds before publishing.
JsonNode snapshot = client.connections().create(descriptor);

Use getCurrent, advance, and revoke on client.connections().

CLI and MCP

mockarty-cli --namespace payments connections create --file gitlab-connection.json
mockarty-cli --namespace payments connections get gitlab-prod
mockarty-cli --namespace payments connections advance gitlab-prod --revision 1 --file gitlab-connection.json
mockarty-cli --namespace payments connections revoke gitlab-prod --revision 2

The embedded MCP server exposes connection_create, connection_get_current, connection_advance, connection_execute (runs a probe or a target request), and connection_revoke. Their descriptor arguments accept exact secret references only. Do not paste credentials into an agent prompt or a descriptor.

Rotation and revocation

• Advance creates a new immutable revision; it does not edit the previous revision in place.
• Every advance and revoke is guarded by the exact current revision.
• Retrying an advance that already landed is safe while its revision is still current: publishing the same descriptor again with the same expectedRevision returns that revision instead of creating a second one. A different descriptor is refused as a revision conflict. Once a later revision is current, even a matching retry of the older request returns 409; load the current revision before editing again.
• After advance, the previous revision is no longer current.
• After revoke, current resolution returns not found, so nothing can reuse the revoked revision.
• Revoking a connection does not delete its referenced secrets. Rotate or remove those separately when required.