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
repoargument is on the list.
Add a source
- Go to Settings → Policies, click External attributes, then click Add source.
- 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
httpsURL 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.
- Tool arguments (optional): up to 8 argument paths, such as
repoorissue.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.
- Key: the name policies use, as in
- Copy the signing secret. Runlayer shows it once. Your endpoint uses it to verify requests.
- 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.
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 ismeta.external.<key>.<attribute>.
field, not in value:
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:
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
nullattribute. A200reply withnullfor an attribute is an answer. The condition reads it as a missing field:equalsand the other positive operators don’t match, and the negated operators (not_*andlist_not_*) do. See Negated operators andnull. - 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.
Negated operators and null
To keep an allow policy from granting on null:
- Use a positive operator. Write
meta.external.tickets.approvedequalsfalseinstead ofnot_equalstrue. - 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 ofnull, or leave the attribute out of the reply so that it counts as a failure.
Build the endpoint
Request
Runlayer sends onePOST per lookup with a JSON body:
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 HTTP200 with every attribute the source declares:
- A text value is at most 256 characters. A list has at most 64 text values.
- Return
nullfor an attribute that has no value for this call. A condition then treats it like any missing field:equalsdoesn’t match andnot_equalsdoes. This is not a failure and does not fail closed. See Negated operators andnull. - A missing attribute, or one of the wrong type, counts as a failure for that attribute.
- Extra attributes are ignored.
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 fromrequest_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.
Verify requests
Requests are signed with the Standard Webhooks scheme, so any Standard Webhooks library can verify them. Each request carrieswebhook-id, webhook-timestamp, and webhook-signature headers.
To verify by hand:
- Base64-decode the part of the secret after
whsec_. That is the HMAC key. - Compute
base64(HMAC-SHA256(key, "{webhook-id}.{webhook-timestamp}.{raw body}"))over the exact bytes received. - Accept the request if any
v1,<signature>entry inwebhook-signaturematches, using a constant-time comparison. - Reject requests whose
webhook-timestampis more than 5 minutes from your clock.
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.