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

# External Attributes

> Let policy conditions read attributes from your own service

An external attribute source is an HTTPS endpoint you host. When a [policy](https://docs.runlayer.com/platform-policies.md) condition reads one of its attributes, Runlayer sends the endpoint a signed request that describes the tool call, and uses the reply as condition values.

Runlayer keeps the decision. Your endpoint returns facts, such as an agent's kind or a ticket's status, and your policies decide what those facts allow.

## When to use one

Policies can already match on the user, their groups, the agent, the connector, the tool, and the tool's arguments. Add an external attribute source when a condition needs a fact that only your systems hold:

* **Classify agents without one account per kind.** Return `kind: "migration"` for an agent your platform registered as a migration agent, and write one policy per kind.
* **Tie access to a ticket.** Return whether the change ticket for a session is approved, and require approval when it isn't.
* **Reuse a risk or data classification.** Return the repositories a user may not touch, and deny tool calls whose `repo` argument is on the list.

To allow or deny on content, use a [custom scanner](https://docs.runlayer.com/custom-scanners.md) instead. A scanner returns a verdict. A source returns attributes.

## Add a source

1. Go to **Settings → Policies**, click **External attributes**, then click **Add source**.
2. Enter:
   * **Key**: the name policies use, as in `meta.external.<key>.<attribute>`. Lowercase letters, digits, and underscores. It can't be changed later.
   * **Name**: how the source appears in settings and in the condition builder.
   * **Endpoint URL**: the `https` URL Runlayer posts to, exactly as entered.
   * **Send with each request**: which facts about the call your endpoint receives. **Subject** and **Acting agent** are on by default. See [Request](#request).
   * **Tool arguments** (optional): up to 8 argument paths, such as `repo` or `issue.project`. Runlayer sends the value of each one. It never sends the whole tool input.
   * **Attributes**: the attributes your endpoint returns. Each has a name, a type (**Text**, **True/false**, or **List of text**), and an optional description. A source has 1 to 32 attributes.
   * **Timeout (ms)**: 200 to 2000. The default is 500.
   * **Cache answers for (seconds)**: 0 to 300. The default is 30, and 0 turns caching off.
   * **Custom headers** (optional): static headers sent on every request, for example an API key for your gateway. They are stored encrypted and never shown again.
3. Copy the signing secret. Runlayer shows it once. Your endpoint uses it to verify requests.
4. Open the source's menu and click **Test connection**. Runlayer sends a test request with the fields the source selects: your own identity as the subject, and placeholder values for the client, session, connector, and tool. Listed arguments are sent as `null`. It shows the status code, the latency, and whether each attribute came back, never the values.

A workspace can have up to 10 sources.

## Use an attribute in a policy

In the condition builder, attributes appear under **External** for conditions on connector tool calls. In the API, the field is `meta.external.<key>.<attribute>`.

```json theme={null}
{ "field": "meta.external.agents.kind", "operator": "equals", "value": "migration" }
```

Put the attribute in `field`, not in `value`:

| Attribute type | Operators | Example |
| - | - | - |
| Text | The text operators, such as `equals`, `begins_with`, `regex` | `meta.external.agents.kind equals "migration"` |
| True/false | `equals` and `not_equals` against `"true"` or `"false"` | `meta.external.tickets.approved equals "true"` |
| List of text | The list operators, such as `list_contains` | `meta.external.risk.restricted_repos list_contains $payload.repo` |

External attributes are read only when a tool is called. When a client lists tools, a tool whose access depends on an external attribute is listed, and the call decides.

Only the sources a call needs are contacted. A tool call whose policies read no external attribute sends no request.

## When a source fails

If a source times out, returns an error, or returns a reply Runlayer can't use, every condition that depends on it fails closed:

| Policy | What happens |
| - | - |
| Allow | It does not grant access. |
| Deny | It denies the call. |
| Approval requirement | Approval is required. |

There is no setting that lets a call through when a lookup fails. A failure applies only to conditions that depend on the source. If another condition in the same group is already false, the group stays false.

Two cases are not failures, so they don't fail closed:

* **A `null` attribute.** A `200` reply with `null` for an attribute is an answer. The condition reads it as a missing field: `equals` and the other positive operators don't match, and the negated operators (`not_*` and `list_not_*`) do. See [Negated operators and `null`](#null).
* **A cached answer.** While a reply is cached, Runlayer doesn't contact the source, so an outage or a changed answer goes unseen until the cache time ends. See [Caching](#caching).

### Negated operators and `null`

> [!WARNING]
>
> An allow policy with `meta.external.agents.kind` `not_equals` `migration` grants access when your endpoint returns `null` for `kind`. A deny policy with the same condition denies.

To keep an allow policy from granting on `null`:

* Use a positive operator. Write `meta.external.tickets.approved` `equals` `false` instead of `not_equals` `true`.
* For a text attribute, add a `regex` `.+` condition on the same attribute, which matches only when a value is present.
* Return a value such as `"unknown"` instead of `null`, or leave the attribute out of the reply so that it counts as a failure.

Each failure is written to the [audit log](https://docs.runlayer.com/platform-audit-logs.md) as an external attribute lookup failure, with the source, the cause, the status code, and the latency.

Deleting a source, or removing an attribute from it, has the same effect on policies that still read it. Change those policies first.

## Build the endpoint

### Request

Runlayer sends one `POST` per lookup with a JSON body:

```json theme={null}
{
  "type": "external_attributes",
  "version": 1,
  "request_id": "0d6f6f0e-6b0b-4a51-9d39-6f5a8f1f2c11",
  "tenant_id": "0b1e7a3c-5d44-4f2a-9c10-11a2b3c4d5e6",
  "source": "risk",
  "subject": { "type": "user", "id": "8f14e45f-…", "email": "ana@example.com" },
  "actor": { "type": "agent", "id": "21c6b9e0-…", "name": "migration-agent" },
  "arguments": { "repo": "ledger-core" }
}
```

| Field | Sent when | Contents |
| - | - | - |
| `subject` | **Subject** is selected | The user the call is made for, with `type`, `id`, and `email`. For an agent acting on its own, the agent, with `type`, `id`, and `name`. |
| `actor` | **Acting agent** is selected | The agent making the call on a user's behalf. `null` when a user calls directly or an agent acts on its own; in that case the agent is in `subject`. |
| `client` | **Client** is selected | The MCP client's `name` and `version`. |
| `session` | **Session** is selected | The session's `id` and `external_id`. |
| `server` | **Connector** is selected | The connector's `id` and `name`. |
| `tool` | **Tool** is selected | The tool's `name`. |
| `arguments` | The source lists tool arguments | One entry per listed path. A value that isn't text, a number, or true/false, or that is longer than 1024 characters, is sent as `null`. |

A selected field with no value is `null`. Ignore fields you don't recognize. New optional ones may be added.

Your endpoint can tell calls apart only by the fields it receives. A source that doesn't send **Subject** returns the same attributes for every user, so a policy can't use it to treat users differently. Select every field your answer depends on.

Runlayer never sends credentials, request headers, IP addresses, roles, or groups.

### Response

Return HTTP `200` with every attribute the source declares:

```json theme={null}
{ "attributes": { "kind": "migration", "approved": true, "restricted_repos": ["ledger-core", "payments"] } }
```

* A text value is at most 256 characters. A list has at most 64 text values.
* Return `null` for an attribute that has no value for this call. A condition then treats it like any missing field: `equals` doesn't match and `not_equals` does. This is not a failure and does not fail closed. See [Negated operators and `null`](#null).
* A missing attribute, or one of the wrong type, counts as a failure for that attribute.
* Extra attributes are ignored.

Anything else counts as a failure of the whole source: another status code (including redirects, which Runlayer doesn't follow), a body that isn't a JSON object with `attributes`, a body over 16 KiB, a timeout, or a connection error. If the connection can't be opened, Runlayer retries once after 100 ms within the same timeout. Nothing else is retried.

**Connection tests** have a `request_id` starting with `test_`.

### Caching

Runlayer keeps a reply for the source's cache time and reuses it for requests with the same body, apart from `request_id`. A source that receives only **Subject** is asked about once per user per cache time on each Runlayer server. Each field you add to the request makes cached answers match fewer calls.

Failures are not cached. Editing a source or rotating its secret discards its cached answers.

A cached reply is used until its cache time ends, whatever happens to the source in between:

* **During an outage**, calls that match a cached reply are decided on it. Calls that don't match one fail closed. Each server has its own cache, so the same call can be allowed on one server and denied on another until the cached replies expire.
* **After your endpoint changes its answer**, for example when a ticket is revoked, Runlayer keeps using the old answer for up to the cache time.

Set **Cache answers for (seconds)** to the longest delay you accept for a revocation. Set it to 0 to ask on every call.

### Verify requests

Requests are signed with the [Standard Webhooks](https://www.standardwebhooks.com/) scheme, so any Standard Webhooks library can verify them. Each request carries `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers.

To verify by hand:

1. Base64-decode the part of the secret after `whsec_`. That is the HMAC key.
2. Compute `base64(HMAC-SHA256(key, "{webhook-id}.{webhook-timestamp}.{raw body}"))` over the exact bytes received.
3. Accept the request if any `v1,<signature>` entry in `webhook-signature` matches, using a constant-time comparison.
4. Reject requests whose `webhook-timestamp` is more than 5 minutes from your clock.

Replies are not signed. Runlayer trusts the reply because it connects to your endpoint over TLS.

### Rotate the secret

Open the source's menu and click **Rotate secret**. For 5 minutes after rotation, Runlayer signs every request with both the new and the old secret, so you can switch your verifier over without rejecting traffic.

### Network requirements

* The endpoint must use `https`. Credentials in the URL aren't accepted. Use a header instead.
* Private-network addresses are allowed, so the endpoint can run next to a self-hosted Runlayer. Loopback, link-local, and cloud metadata addresses are refused.
* Don't compress responses. Runlayer sends `Accept-Encoding: identity`.

Your endpoint is on the request path of every tool call whose policies read it, so keep it fast. Sources for one call are contacted at the same time, so a call waits for the slowest one.

Each Runlayer server runs at most 20 lookups at a time for your organization. A lookup that is still waiting for its turn when the source's timeout ends counts as a timeout, without a request to your endpoint. Cached answers don't wait.

## Test policies

The policy simulator does not contact your endpoint. A simulated call whose result depends on an external attribute is reported as conditional, with the attribute named.


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