Relay management, NIP-86 and the admin layer behind Nostr relays
A relay can feel like neutral infrastructure from the outside. From the operator chair it is a living system: keys are allowed or banned, event kinds are accepted or refused, queues need moderation, IPs can attack, metadata changes and every admin button carries trust.
Relay management is operations, not glamour
It is easy to talk about relays as if they are simple pipes. Accept event, store event, serve event. Real relays are messier. They receive spam, malformed events, abusive traffic, legal pressure, oversized content, bad clients, experimental event kinds, wallet traffic, group traffic, private rooms, search queries and people who expect the relay to keep working forever. Someone has to decide what the relay is for and then enforce that decision.
That enforcement is relay management. It is the backstage layer behind the public endpoint. It decides who can write, which keys are blocked, which event ids are banned, which event kinds are allowed, which IP addresses are blocked, what sits in a moderation queue, what metadata the relay publishes and how the operator changes policy without SSH rituals and random database edits.
Management is not automatically bad. Without it, public relays collapse under abuse, private relays leak boundaries, group relays cannot enforce roles, paid relays cannot protect subscribers, wallet relays cannot stay narrow and local relays cannot keep real rooms safe. The question is not whether relays need admin tools. They do. The question is how those tools stay authenticated, understandable and proportional.
Nostr's deeper promise is not that infrastructure has no operators. It is that operators do not own your identity everywhere. A relay admin can refuse hosting on that relay, but cannot delete your key from the network. A management API should respect that boundary. It should help an operator run a relay, not become a hidden platform control panel pretending to be protocol neutrality.
Good relay management has hard edges. It knows who can use the controls. It logs or documents meaningful actions. It separates policy from whim. It keeps dangerous methods away from normal client surfaces. It publishes enough metadata that users understand the relay. It gives operators power without making power invisible.
What NIP-86 actually does
NIP-86 defines an optional Relay Management API. It is made available as a JSON-RPC-like request-response protocol over HTTP, on the same URI as the relay's WebSocket endpoint. When the relay receives an HTTP or HTTPS request with the content type application/nostr+json+rpc, it can parse a JSON document with a method and params array, then respond with a result or an error.
The shape is deliberately simple. A request can look like a method name plus parameters. A response can return arbitrary result data or an error message. That simplicity matters because relay implementations differ. NIP-86 gives them a shared management vocabulary without forcing every relay to support every possible admin action.
The method list includes supportedmethods, which lets an admin client ask the relay what management calls it supports. That is the first healthy pattern. Do not assume every relay supports every method. Ask. Then show only the controls that exist. A strfry deployment, a nostream deployment, a custom Khatru relay and a local app relay may expose different management surfaces.
Several methods manage pubkeys: banpubkey, unbanpubkey, listbannedpubkeys, allowpubkey, unallowpubkey and listallowedpubkeys. Those are the access and exclusion levers. They can define who is blocked from writing or who is explicitly allowed. On a public relay, bans may fight abuse. On a private relay, allowlists may define membership. On a paid relay, payment systems may map into allowed keys.
Other methods manage individual events: listeventsneedingmoderation, allowevent, banevent and listbannedevents. Those are moderation-queue tools. They let an operator review specific event ids, approve them or ban them. This is important because good moderation is not only key-based. A generally legitimate user can publish one bad event. A bad event can appear from a key that should not be fully banned yet.
NIP-86 also includes relay presentation methods such as changerelayname, changerelaydescription and changerelayicon. Those may look cosmetic, but they affect user trust because NIP-11 metadata is the relay's public door sign. If the relay name, description or icon changes, clients and users may experience that as a trust event.
There are event-kind methods: allowkind, disallowkind and listallowedkinds. These are essential for specialized relays. A wallet relay may only want NWC-related events. A group relay may accept group events. A local venue relay may accept announcements, RSVPs and community notes. A broad public relay may allow many kinds. Event-kind policy is how a relay stops being vague.
Finally, the spec includes IP controls: blockip, unblockip and listblockedips. That is infrastructure reality. Abuse does not only come as pubkeys. It comes as traffic, scraping, floods, botnets and broken clients. IP controls are blunt, but operators sometimes need blunt tools to keep a relay alive.
Authorization matters because this API is dangerous
NIP-86 requires authorization. The request must include an Authorization header with a valid NIP-98 event, except the payload tag is required, and the u tag is the relay URL. If authorization is not provided or is invalid, the endpoint should return a 401 response. That detail is not decoration. It is the safety boundary around the admin room.
NIP-98 signs HTTP authentication with a Nostr event. That means management calls can be authorized by cryptographic identity rather than a random bearer token passed around in a dashboard. The admin key signs the request. The relay verifies it. The payload tag binds the signed event to the request body. The URL tag binds it to the endpoint. That reduces replay and confusion when implemented correctly.
Still, admin keys are high-risk. If a normal social key is also a relay admin key, a compromise becomes operational disaster. A signer bug, browser extension compromise or exposed nsec could let an attacker ban users, change metadata, allow spam, disallow event kinds or block IPs. Operators should use dedicated admin keys, hardware or remote signing where appropriate, and minimal permissions if the relay implementation supports them.
Clients must not treat NIP-86 as a normal user capability. A regular Nostr client should not casually probe management endpoints or show admin controls unless the user explicitly enters operator mode. Management is not "settings." It is infrastructure control. The UI boundary should be obvious, serious and boring.
Authorization errors should be clear. A 401 response means the request is not authenticated. A method-level error means the caller may be authenticated but the action failed. An unsupported method should not look like a successful no-op. Admin tools should never leave the operator guessing whether a ban, allow or metadata change actually happened.
Pubkeys, events and event kinds are different levers
A pubkey ban is a broad tool. It says this identity cannot write or is blocked from some relay function. That can be necessary for spam, impersonation, harassment, illegal material or repeated abuse. It can also be overbroad. One key may have many good events and one bad event. One compromised client may behave badly for a short time. A broad ban should be a deliberate decision, ideally with a reason.
An allowlist is a different tool. It is not mainly punishment. It defines membership or admission. A private relay, paid relay, local relay, group relay or application relay may use allowlists to accept writes only from known keys. That is healthy when the relay is honest about its purpose. A relay that is member-only should say so. A relay that pretends to be public but silently uses allowlists creates confusion.
Event moderation is more precise. If a single event violates policy, banning the event may be enough. The NIP-86 event methods allow relays to surface events needing moderation and then allow or ban individual ids. That gives operators a middle path between accepting everything and banning whole identities. It also makes review workflows possible.
Event-kind policy is quieter but just as important. Relays do not have to accept every event kind. A relay might disallow high-volume ephemeral kinds, app-specific data it does not understand, wallet events outside its role, experimental events or media metadata it cannot police. The allowkind and disallowkind methods make that boundary manageable through the standard API.
Good operator practice separates these levers. Do not ban a pubkey when an event ban is enough. Do not pretend an event-kind restriction is moderation of a person. Do not use IP blocks when key-based controls solve the problem. Do not use allowlists without telling users the relay is restricted. The more precise the lever, the easier it is to explain the decision.
Reason strings matter. NIP-86 methods often allow an optional reason. Use it. "spam flood from compromised key" is better than an empty ban. "member-only relay" is better than silent rejection. "event kind not accepted here" is better than mystery. Reasons do not solve every dispute, but they create a record and reduce operator amnesia.
IP blocking is ugly and sometimes necessary
Nostr identity is key-based, but servers still receive packets. Abuse can come from IP ranges, data centers, botnets, broken scrapers, websocket floods and clients that retry badly. A relay can be philosophically open and still need IP-level protection. If the server dies, nobody's principled speech gets served.
NIP-86 includes IP block methods because operators need an emergency brake. blockip and unblockip are blunt. They can catch innocent users behind shared networks, VPNs or mobile carriers. They can also stop a flood faster than key-level moderation when keys are cheap and the attack is traffic-based. The right use is proportional and reviewed.
IP controls should not become lazy moderation. If a relay uses IP blocks to enforce political or social policy while pretending to be key-based and open, trust erodes. Use IP blocks for infrastructure abuse, legal risk or severe attack traffic. Use pubkey, event and event-kind controls for protocol-level policy. Keep the difference clear.
Operators should record why IP blocks exist and revisit them. A temporary attack block can become permanent damage if nobody cleans it up. A list of blocked IPs without reasons becomes folklore. listblockedips exists for a reason: management should be inspectable by the admin team, not trapped in one operator's memory.
Clients normally should not see IP controls. They are operator tools. But users should see clear relay errors when their traffic is blocked, if safe. "blocked: relay is refusing this connection" is better than infinite reconnects. During attacks, even that may be hard. The point is to avoid making infrastructure defense look like random brokenness whenever possible.
Relay metadata is part of management
NIP-11 is the public face of relay management. Name, description, contact, supported NIPs, software, limitations, payment and policy links tell users what kind of relay they are dealing with. NIP-86 methods that change name, description and icon touch that trust surface directly. A relay's door sign should not change casually.
If a relay moves from public writes to paid writes, the metadata should change. If it narrows accepted event kinds, the metadata or policy page should change. If it begins requiring authentication, clients need to know. If it stops serving historical data, users need to know. Management tools make changes easy; responsible operation makes changes visible.
Admins should treat metadata changes like releases. What changed? Why? Who changed it? When? Does the policy page match? Do clients see the new supported NIPs? Did payment requirements change? Does the relay still describe itself accurately? Sloppy metadata creates product bugs because clients often rely on it to explain the relay.
Metadata should also avoid overpromising. A relay that says "public relay for everyone" but uses allowlists is misleading. A relay that claims search support but only searches a narrow corpus should explain scope. A relay that lists NIP-86 support should not imply anyone can manage it. NIP-86 is admin-only, not a public convenience endpoint.
Public policy can be short. "Public read, paid write." "Member-only write." "Accepts kind 1, 0, 3 and NIP-65 lists." "Rejects malware and spam." "Honors NIP-40 expiration." "Deletion requests are reviewed." The important thing is that the management state and the public description do not drift apart.
A sane operator workflow
A good relay admin workflow begins before the first abuse report. Decide the relay purpose. Publish NIP-11 metadata. Decide admin keys. Decide who can use management tools. Decide logging. Decide backup and restore. Decide which event kinds are accepted. Decide whether writes are public, authenticated, paid or allowlisted. Decide how moderation reasons are written.
Next, build a moderation path. Incoming events may be accepted, rejected, queued, allowed later or banned. A queue is only useful if someone reviews it. If a relay exposes listeventsneedingmoderation, there should be a human or trusted process behind it. Otherwise it becomes a graveyard of maybe-bad events nobody owns.
Then build an access path. How does a new member or paid user become allowed? How does a revoked user lose access? How do you rotate a compromised key? How do you unban after a false positive? How do you document reasons? The NIP-86 methods give you verbs, but the operator still needs a process.
Build an emergency path too. If the relay is under attack, who can block IPs? Who can pause writes? Who can narrow event kinds? Who can update metadata to announce degraded service? What gets logged during the incident? What gets reviewed after? Emergency admin power is safest when it is planned before panic.
Finally, build a review rhythm. Bans should not be eternal by accident. IP blocks should not be forgotten. Allowed keys should not pile up forever. Event-kind policy should match actual use. Metadata should stay current. NIP-86 can make management easier, but it cannot replace the discipline of looking at your own relay.
Client boundaries keep admin power from leaking
Most Nostr users should never see NIP-86 controls. They should see relay status, policy, auth requirements, payment requirements and meaningful publish errors. They should not see "banpubkey" beside a post unless they are explicitly operating a relay. Admin actions need a different UI mode, different keys and different mental weight.
Operator dashboards should show danger clearly. Banning a pubkey, banning an event, blocking an IP, changing accepted kinds and changing relay metadata should feel like infrastructure actions, not casual feed interactions. The UI should show the target, reason, affected scope and expected outcome before committing.
Admin clients should call supportedmethods first and adapt. A dashboard that shows unsupported buttons trains operators to distrust the tool. A dashboard that silently fails is worse. If a relay does not support listallowedkinds, say so. If a method returns an error, show it. If authorization fails, explain the NIP-98 signing requirement.
Normal clients can still benefit from management indirectly. Clear relay errors, accurate NIP-11 metadata, visible accepted kinds, readable policy and honest auth/payment states are downstream effects of good management. Users do not need the admin panel. They need the public behavior to match the published rules.
Builders should be especially careful with signers. Asking a signer to create NIP-98 admin authorization events should be explicit and rare. The user should see the method, relay URL and payload meaning. A generic "sign event" popup is not enough for management operations. Admin signing needs ceremony because the consequence is real.
Risks and better patterns
The first risk is key compromise. Use dedicated admin keys, limit where they live, prefer hardened signing paths, and avoid mixing social identity with relay administration. If possible, separate roles: metadata manager, moderation reviewer, emergency operator and billing owner do not always need the same power.
The second risk is invisible policy drift. The relay begins as open, then gains allowlists, event-kind restrictions, spam filters, paid writes and IP blocks. Each change may be reasonable, but users never see the new reality. Fix this with metadata updates, policy notes and clear errors. Policy drift is less dangerous when it is visible.
The third risk is admin monoculture. If many relays use the same hosted management dashboard or shared admin service, compromise or policy pressure can spread. NIP-86 standardization should increase interoperability, not centralize control. Operators should understand their own control plane and avoid unnecessary dependency.
The fourth risk is over-automation. Auto-ban based on reports, spam scores or IP heuristics can save time and create false positives. Automation should be proportional to the relay role. A small private relay can be strict. A major public relay should review more carefully. Reasons, logs and appeal paths matter more as the relay becomes more important.
The better pattern is small, explicit and inspectable. Use NIP-86 where it fits. Use NIP-98 for authorization. Publish NIP-11 metadata. Keep policies short but real. Use the narrowest management action that solves the problem. Log reasons. Review old blocks. Keep admin keys separate. Let users exit without pretending every relay is a universal public square.
Admin key design
The first practical decision is which key signs management requests. Do not use a famous public social key just because it is convenient. A relay admin key is closer to an infrastructure credential than a profile. If it can ban pubkeys, change relay metadata, allow event kinds or block IPs, losing it can damage everyone who depends on the relay.
A dedicated admin key gives you cleaner separation. Your public social identity can remain public while the relay-admin identity stays in a tighter signing environment. If the relay is run by a team, you may want multiple admin keys or role-specific keys. One key can review moderation. Another can change metadata. Another can handle emergencies. NIP-86 itself does not prescribe a full role system, but relay implementations and dashboards can build safer controls around the standard methods.
Key rotation should be planned. If an admin key is compromised, how do you remove it? Where is the current list of admins stored? Is it in relay configuration, an environment variable, a database, a NIP-11 extension, a deployment secret or a separate service? Who can deploy the change? How fast can you act? These details are boring until the wrong key signs the wrong management call.
Use signing ceremonies that match risk. A browser extension that signs public notes all day may not be the right surface for relay management. A remote signer, hardware-protected key, dedicated admin client or isolated operator browser may be better. At minimum, the signing prompt should show the relay URL, management method and payload meaning. "Sign event" is not enough when the event authorizes an admin action.
Also keep human accountability. If several people can manage the relay, write down who did what. A NIP-86 call can be technically valid and socially unclear. Team operations need records: reason, time, operator, method, target, result and follow-up. The more important the relay, the less you can rely on memory.
Moderation queues need ownership
A moderation queue is a promise to review, not a place to hide discomfort. If events needing moderation pile up and nobody checks them, users experience random delay or disappearance. A relay that queues events should define the queue policy: what triggers review, who reviews, how often, what outcomes exist and whether users receive an explanation.
Some triggers are technical. Oversized events, suspicious links, rare event kinds, malformed tags, high-frequency writes or new keys may be queued. Some triggers are social. Reports, known scams, harassment patterns, impersonation, adult media or local community rules may send an event to review. Mixing those triggers without labels creates confusion. The operator should know whether a queued event is suspected spam, unsupported type, legal risk or community conflict.
NIP-86's listeventsneedingmoderation, allowevent and banevent methods give a basic flow, but the human product around it matters. The admin dashboard should show event id, author, kind, content preview when safe, tags, relay reason, report context and time in queue. It should also show the consequence of allowing or banning. Does banning remove a stored event? Does it reject future writes of the same id? Does it affect search? Does it notify clients through errors?
Queues should be proportionate to relay role. A public firehose relay cannot manually review everything. It needs automated filters, rate limits and narrow review paths. A private club relay can review more personally. A wallet relay should avoid broad social moderation and focus on valid, authenticated, narrow event flows. A local relay can have community moderators. The same NIP-86 method can support very different policies.
When a decision is made, the reason should be kept. Not every reason needs to be public in full, especially when safety or legal issues are involved. But the operator should retain enough internal context to avoid repeating mistakes. "Banned" is not a reason. "malware link," "impersonation," "member request," "unsupported kind" and "spam burst" are reasons.
Paid, member and local relays
Relay management becomes especially visible in paid and member spaces. A paid relay has to connect payment state to write access. That usually means an allowlist or equivalent entitlement. A member relay has to connect human membership to pubkeys. A local relay has to connect a real room, venue or group to a relay boundary. NIP-86 does not handle billing or identity proof by itself, but it gives operators the verbs needed to update access.
The danger is stale access. A user pays, but the key is not allowed. A member leaves, but the key stays allowed. A subscription expires, but write access remains. A user rotates keys, but the old key keeps privileges. The management workflow must include synchronization between the human system and the relay system. Otherwise the relay's actual policy drifts away from the membership reality.
Local relays also need event-kind discipline. A venue relay may accept announcements, RSVPs, menus, badges, group notes and local media metadata. It may not need global public spam, wallet events or arbitrary app data. Event-kind methods can keep the relay focused. The local room becomes more reliable because it does not accept everything the wider network invents.
Member relays should tell users what happens when they leave. Are their old events kept? Are they hidden from the local room? Are they still readable? Does the relay keep public event history for continuity? Does it honor deletion requests? Access management and archival policy are connected. Removing a key from future writes is not the same as removing old content.
Paid relays should avoid pretending payment equals trust. Payment reduces spam friction, but bad actors can pay. A paid relay still needs event moderation, reports, abuse controls and key revocation. The best paid relay management combines economic friction with actual policy, not with blind confidence.
Logs, exports and recovery
Admin actions should be logged somewhere the operator can inspect. A log does not have to publish sensitive information, but it should preserve the management history: method, target, reason, operator key, timestamp and result. If a key was banned by mistake, you need to know when and why. If the relay name changed unexpectedly, you need to know who signed it. If an IP block is hurting users, you need to trace it.
Logs should survive restarts and deployments. If they live only in console output, they will disappear exactly when you need them. If they include sensitive data, they need access controls. If they are too noisy, nobody will read them. Good operations means finding the middle: enough detail to reconstruct decisions, not so much that the log becomes another unmanaged liability.
Exports matter because relay state is more than events. Banned pubkeys, allowed pubkeys, banned events, allowed event kinds, blocked IPs, metadata and moderation queues can all become operational state. If you migrate software, rebuild a relay, recover from corruption or split a community relay, you need to move that state or intentionally reset it. A relay backup that preserves events but loses all policy can reopen old abuse.
Recovery planning should include management keys. If the only person with admin access disappears, the relay may become unmanaged. If the only admin key is lost, you may need server-level access to rotate it. If a deployment secret leaks, you may need to revoke and rebuild. The relay's governance is part of its uptime.
Public relays should consider publishing a lightweight changelog for major management changes. Not every spam ban belongs in public. But changes to admission, accepted event kinds, payment, retention, auth requirements or relay identity should be visible. Users do not need your whole admin log. They do need to know when the room changed shape.
What users should see from good management
You should not need admin access to benefit from good relay management. You should feel it in clearer errors, more accurate metadata, stable policy and fewer mysterious failures. When a relay rejects an event because the kind is not allowed, your client should be able to say that. When writes require membership, the relay should not pretend to be public. When a relay is paid, the payment state should be visible before you lose a post.
Good management also shows up as restraint. A relay that bans whole keys for every small issue will feel arbitrary. A relay that never bans anything will drown in abuse. A relay that silently blocks IPs will feel broken. A relay that publishes reasons and uses narrow tools will feel more trustworthy even when it refuses you.
As a user, you can judge management without seeing the dashboard. Does the relay publish useful NIP-11 metadata? Does it state contact and policy? Does it return readable errors? Does it support the NIPs it claims? Does it behave consistently with its stated role? Does it handle auth and payment cleanly? Does it recover from incidents? These are public signs of private discipline.
If a relay is important to your work, ask stronger questions. Who operates it? How is it funded? What happens if the operator leaves? What event kinds are accepted? Are deletion and expiration honored? Is there a backup? How are bans reviewed? Can you export or mirror your events? A serious relay operator will not be offended by serious infrastructure questions.
Good management is not a luxury feature. It is what lets a relay stay useful after the novelty fades. The protocol gives you exit. Operators give you reliability. The healthiest relay ecosystem needs both.
Management without platform gravity
The fear around management APIs is reasonable. Once a relay has admin tools, it can start to feel like a platform. Ban lists, moderation queues, metadata, allowed kinds, payment gates and dashboards are all familiar from centralized systems. The difference must be architectural and cultural: scope stays local, policies are visible, users can move, and keys remain portable.
A relay admin should not pretend to be the sheriff of Nostr. They are the steward of one endpoint. That endpoint can be broad and important, but it is still one endpoint. A NIP-86 action should change that relay's behavior, not the user's identity across the network. Clients should reinforce this by saying "this relay rejected the event" instead of "you are banned from Nostr."
Platform gravity appears when one relay's management decisions become default reality for too many users. If a dominant relay bans a key and most clients depend on that relay, exit becomes theoretical. The antidote is relay diversity, better client routing, visible relay lists, local relays, paid alternatives, personal archives and search tools that do not collapse everything into one dependency.
Management APIs can actually help reduce platform gravity if they make it easier to run more relays well. A local operator with a usable admin API can run a community relay. A paid operator can manage access without writing custom database tools. A developer can build dashboards that work across implementations. Standardization lowers the barrier for many competent operators instead of concentrating power in the few who can maintain bespoke stacks.
That is the correct ambition for NIP-86: not one big admin system, but many relays that can be operated responsibly. The standard verbs are there so operators can keep their rooms usable, not so one room can become the whole building.
Sources worth opening
Open these when you want the standards and adjacent relay-management layers.
- NIP-86: Relay Management API
- NIP-98: HTTP Auth
- NIP-11: Relay information document
- NIP-42: Authentication of clients to relays
- NIP-56: Reporting
- nostream: relay implementation with operator-focused configuration
- Khatru: Go framework for custom Nostr relays
- strfry: high-performance Nostr relay