Plexara
What you will take away from this lesson
Blue Harbor Wholesale, the fictional supplier whose price sheet the 500 series registered, wants to see how its products are stocking across ACME’s regions so its replenishment system can plan deliveries. The answer is in ACME’s warehouse. Exporting a file every morning would be stale by noon, and giving the supplier a login to the warehouse is out of the question.
An endpoint answers it: a lookup the supplier’s system calls with a key of its own, that returns regional totals and nothing else, under a rate the supplier cannot exceed, with every request on the record.
Learning Objectives
- 01Choose between the three access modes for an endpoint.
- 02Admit a partner system with an API key of its own, and name who else an endpoint admits.
- 03Set an endpoint’s rate and a caller’s own rate, and read what a caller past either is told.
- 04Find every request in the audit log, and every refusal counted by reason.
- 05Read the Endpoints page an administrator watches.
- 06Use a signed, single-use token for a link that is authorized in advance.
Where this lesson sits
Lesson 701 put an automation at an address and answered requests from a public page. This lesson decides who may call, and keeps the record of who did.
700 Series: Endpoints and Forms
- 701An automation that answers a requestWhat an endpoint is, the request a handler is handed and the answer it returns, who binds it, the limits a request runs under, and what a caller is told.
- 702A lookup a partner system callsThe three access modes, API keys and per-caller limits, one audit row per request, refusals by reason, signed tokens, and the Endpoints page.
- 703Your first formA form the agent writes: fields, live choices, field-by-field refusals, the checks the platform runs first, the hosted page, and submissions as a table.
- 704Putting the form on your site, or in a reportEmbedding in an asset and on an allowed site, named bot checks, the honeypot, and the minimum fill time.
- 705Sensitive fieldsEncryption before storage, who reads in clear and where, audited reads, exports, and why a file field cannot be sensitive.
- 706From submission to actionAn automation that runs once per submission, validation against live data, bursts and failures, and writes to other systems.
- 707Capstone: the supplier form end to endThe demo tenant’s supplier program assembled: form, page, table, intake automation, and a report joining applications to the warehouse.
The 700 series builds on the automations of the 600 series: an endpoint is an automation that answers a request, and a form is an endpoint that people fill in.
Three access modes
Who may call an endpoint is set once, on the binding, as one of three modes.
The three access modes
authenticated
API key or session
- Admits a platform API key or a signed-in browser session, among the callers the binding names. An anonymous request is answered 401. The handler is told who the caller is.
bot_check
a named check
- Admits anyone who passes the bot check the binding names, on the methods it checks. The store finder in 701 uses one. Lesson 704 covers the checks.
public
anyone
- Admits anyone with no check at all. Every page that lists the endpoint marks it as answering anyone.
Every endpoint has exactly one mode, and an administrator chooses it when binding. An automated caller, a partner’s system included, calls an authenticated endpoint with an API key.
Who an authenticated endpoint admits
An authenticated endpoint admits no one until its binding names them, which keeps an address from opening wider than intended.
Who an authenticated endpoint admits
- 1
Name who is admitted
An authenticated binding lists its callers: api_key:<name> for one key, persona:<name> for everyone whose roles resolve to that persona, or * for every authenticated caller. An empty list admits no one.
- 2
Administrators are always admitted
An administrator reaches every endpoint whatever the list says, as on every other surface.
- 3
External people never are
A person of an External persona reaches no endpoint at all. Clients and partners who sign in to the portal see what is shared with them; systems call with keys.
- 4
A key belongs to its system
An administrator issues the key in the portal under Admin, names it after the system that holds it, and sets an expiry. Its value is shown once.
The stock lookup
The agent wrote the lookup from a sentence: answer the supplier’s stock position for one SKU, by region, and nothing at store level.
acme-partner-stock, the handler (query shortened)
def handle(req):
"""Answers a supplier partner's stock position for one SKU, by region."""
sku = req["params"]["sku"].upper()
if not sku.startswith("SKU-") or len(sku) != 10:
return {"status": 400, "json": {"error": "sku must look like SKU-001795"}}
rows = platform.query(
"SELECT r.region_name AS region, count(*) AS stores, " +
"sum(i.quantity_on_hand) AS on_hand, sum(i.quantity_reserved) AS reserved, " +
"count_if(i.quantity_on_hand <= i.reorder_point) AS stores_at_or_below_reorder, " +
"count_if(i.quantity_on_hand = 0) AS stores_out_of_stock " +
"FROM warehouse.public.inventory i ... WHERE p.sku = :sku GROUP BY r.region_name",
params = {"sku": sku},
connection = "acme",
)
if not rows["rows"]:
return {"status": 404, "json": {"error": "no stock is tracked for that sku"}}
caller = req["caller"] or {}
return {"json": {"sku": sku, "requested_by": caller.get("email", ""), "regions": rows["rows"]}}The answer is regional totals for one SKU: how many stores carry it, units on hand and reserved, and how many stores sit at or below their reorder point or are out of stock. Store-level rows and prices never leave. The handler reads who called from req["caller"], which the platform fills from the key, never from anything the caller sent.
Binding it for one key
An administrator bound it as an authenticated endpoint that admits the supplier’s key, with a rate for the supplier and one for the endpoint.
Binding it for one key
What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.
→ manage_script
{
"command": "endpoint_set",
"name": "acme-partner-stock",
"endpoint": "partner-stock",
"methods": ["GET"],
"path": "/{sku}",
"auth_mode": "authenticated",
"callers": ["api_key:blue-harbor-partner"],
"rate_limit": 120,
"caller_rate_limit": 30,
"timeout_seconds": 15
}
← {
"endpoint": "partner-stock",
"enabled": true,
"url": "https://mcp-demo.plexara.io/endpoints/partner-stock/{sku}"
}The key blue-harbor-partner was issued by an administrator with read-only roles and a one-year expiry. The endpoint admits that key and nobody else but administrators. The supplier’s system may make 30 requests a minute; the endpoint as a whole takes 120.
One request from the supplier
The supplier’s system calls once per SKU it plans, and gets back eight regions of totals.
One request from the supplier
What the calling system sends. This is the HTTP exchange Blue Harbor Wholesale’s replenishment system has with the endpoint, shown for the technical reader. The calling system sends it on its own; nobody types it.
GET /endpoints/partner-stock/SKU-000012
Authorization: Bearer <the blue-harbor-partner key>
200 OK
{
"sku": "SKU-000012",
"requested_by": "[email protected]",
"regions": [
{ "region": "Central", "stores": 8, "on_hand": 706, "reserved": 94,
"stores_at_or_below_reorder": 2, "stores_out_of_stock": 1 },
{ "region": "Mid-Atlantic", "stores": 53, "on_hand": 5062, "reserved": 494,
"stores_at_or_below_reorder": 10, "stores_out_of_stock": 2 },
{ "region": "Midwest", "stores": 64, "on_hand": 5705, "reserved": 574,
"stores_at_or_below_reorder": 13, "stores_out_of_stock": 0 },
... five more regions
]
}Where the requests come from
Where the partner’s requests come from
server to server
- The supplier’s replenishment system calls from its own servers with the key in a header. No browser, no allowed origin needed.
audited as
- [email protected], the email the key was issued with.
What a refused caller is told
A request that fails a check is refused before the handler runs. Each reason has its own status, and each refusal is counted.
Refusals, counted by reason
credential
401
- No key or session, or one the platform refused. The demo tenant counted four, from a test with a made-up key.
caller
403
- A valid key or session that the binding’s callers list does not name.
caller_rate_limit
429
- One caller past its own rate while other callers are still answered. The demo tenant counted 27 when the supplier’s system sent 90 requests at once.
rate_limit
429
- The endpoint past its total rate.
bot_check
403
- No bot check answer, or one that was altered, expired, already used, or issued for another endpoint.
body_limit
413
- A body larger than the binding allows.
origin
403
- A browser asking from a website the binding does not list.
A refusal happens before the handler runs, so it costs no query and writes no audit row. Each is counted instead, by endpoint, hour, and reason, and the counts are kept for 30 days. A flood stopped at the door moves a counter rather than filling the log.
One audit row per request
Every request the handler answered is on the record, with who called and what they were told.
The audit row every answered request writes
source
- endpoint
event kind
- endpoint_request
tool
- endpoint:partner-stock
parameters
- The endpoint, the automation and its version, the method, the status, the access mode, and the caller.
the handler’s calls
- Each query the handler ran is its own audit row under script:acme-partner-stock, carrying the request’s session id so the two are read together.
A request writes no run to the automation’s history: it is not a run. The audit log is the record, read in the portal’s audit section like any other call.
The Endpoints page
An administrator watches every endpoint on the deployment from one page, without opening automations one at a time.
Admin > Automations > Endpoints, partner-stock over a day
- requests answered, all from one caller
- 169
- refused before the handler ran
- 31
- median time to answer
- 337 ms
- p95 time to answer
- 1.25 s
The Endpoints page lists every binding on the deployment with its automation, owner, methods, access mode, whether it is on, and over the last day or week its requests, failures, refusals, p95, and last request. It filters by access mode and by on or off.
A row opens the endpoint’s own page: requests by status class an hour a bar, refusals beside them with their reasons, who an authenticated endpoint admits and its busiest callers (here, [email protected]), and the requests that failed. The store finder’s page on the same day showed 127 requests, 14 refused at the bot check, and a p95 of 483 ms.
Calls from another website
Links authorized in advance
Some requests should work for one person, once. An automation can mint a signed token for that and check it when the request comes back.
Signed tokens for links authorized in advance
- 1
Minted by the automation
platform.mint_token(claims, ttl, secret) returns a token carrying a few claims, good for up to 30 days. The key is a stored secret an administrator created; the automation never holds its value.
- 2
Checked when it comes back
platform.verify_token(token, secret) answers the claims, or a reason: expired, tampered, other_endpoint, used, or malformed. The handler decides what to answer.
- 3
Bound to the endpoint
A token minted in a request works only at that endpoint, or at the endpoints it names.
- 4
Single use when asked
With single_use, the verify that accepts the token records it, and a second use on any server is answered used.
A token suits a link sent to one person for one purpose: a credit application that opens once, an order-status page for one order, a survey for one customer. No recording or test ever holds a token that would be accepted.
Next: a form
Key terms
Five terms cover who may call an endpoint and how calls are recorded.
Key Terms
- API key
- A credential an administrator issues for a system, named after it, with roles and an expiry. Its value is shown once.
- Callers
- The list on an authenticated binding naming who it admits: keys, personas, or every authenticated caller.
- Caller rate limit
- Requests a minute one authenticated caller may make, separate from the endpoint’s total.
- Refusal
- A request turned away before the handler runs, answered with its status and counted by reason.
- Signed token
- A short-lived value an automation mints and later verifies, optionally once, for a link authorized in advance.