Quick start
Each accepted order reserves one eligible .uk or .co.uk release within DropSnare. Your receipt records your place. Registry dispatch is paused while the registrar clients are in development. Monthly statements distinguish costs you incurred from costs another registrar paid for you. Payments on a balance due open once DropSnare supplies verified bank details.
Base URL https://api.dropsnare.co.uk/api/v1. Send Content-Type: application/json on requests with a JSON body. All drop times are UTC. Account time zones are presentation preferences.
- Create an account with
POST /auth/register, including your listednominet_tag. Save the returned bearer token privately. Submit the code sent to your email viaPOST /auth/verify-email. - Complete registrar setup on the website at Registrar setup, then create the intended registrant through
POST /registrant-profiles. Supply the returned profile ID with your order or set it as your account default. - Use
GET /dropsto search the daily calendar. Check the entry and its freshness withGET /drops/{domain}. A name missing from this file has no published drop entry here. The file cannot establish real-time registry availability. - Send
POST /backorderswith your bearer token and a newIdempotency-Keyfor each intended order. Reuse that key for a retry with the same payload. A competing account receives409. The successful response contains your order ID. - Retrieve your order through
GET /backorders/{id}. UsePOST /backorders/{id}/cancelbefore the cancellation cutoff. Integration keys can be restricted to the permissions they need.
POST /api/v1/backorders
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN
Idempotency-Key: 673d60e1-14ec-47fa-943a-9ebb69240256
{"domain":"example.co.uk","registrant_profile_id":42}
Replace the sample name with a confirmed release and the profile ID with your own. API errors use HTTP status plus a machine-readable error code. On a rate-limit response, respect the Retry-After header. See the machine-readable OpenAPI definition for the full HTTP contract.
Accounts, credentials and registrant profiles
All paths below use the /api/v1 prefix. Send JSON with Accept: application/json. Authenticated requests use Authorization: Bearer <access_token>. The public API gives each account its own orders, registrant directory and credentials.
Sign up and log in
| Method and path | JSON body | Result |
|---|---|---|
POST /auth/register |
name, email, password, nominet_tag, optional IANA timezone |
201 with data.user, data.verification_sent, data.access_token, data.token_type and token metadata |
POST /auth/login |
email, password |
200 with a restricted password-authenticated session and the next verification step |
POST /auth/logout |
None. Send the current bearer token. | 204 after revoking that token |
GET /account |
None. Use a session or a key with account:read. |
200 with the private account record |
PATCH /account |
Any of name, IANA timezone, default_registrant_profile_id (integer or null). Account session required. |
200 with updated settings |
Use a currently listed Nominet registrar tag when creating an account. An unavailable or stale registry directory returns HTTP 503. You can complete setup at the returned data.onboarding_url. A public listing validates the tag name. The member must then verify control, the default contact, registry permissions, billing and the device connection before using the catch service.
Passwords must contain at least 8 characters and at most 72 bytes. Email addresses are case-normalised. The default timezone is Europe/London. API dates are supplied in UTC. Your application can use the saved time zone when displaying them. Finish the second factor within ten minutes of password authentication. Successful verification issues a new account session valid for 24 hours. Treat tokens as secrets and send them only over HTTPS.
Verification, password recovery and email changes
| Method and path | JSON body | Result |
|---|---|---|
POST /account/verify-email |
None. Account session required. | 202 after sending a verification code, or 204 if already verified |
POST /auth/verify-email |
token from verification email |
204 on success |
PUT /account/password |
current_password, new password. Account session required. |
200 with one new session. Previous account sessions, integration keys and outstanding email action codes are revoked. The authenticator and its backup codes remain active. |
POST /auth/forgot-password |
email |
202 acknowledgement for both known and unknown accounts when mail is configured |
POST /auth/reset-password |
Recovery token, new password |
204. Log in again. |
POST /account/email-change |
email (new address), current_password. Account session required. |
202 after sending a code to the requested address |
POST /auth/confirm-email-change |
Email-change token |
204. The new address takes effect and previous credentials are revoked. |
Each email action uses a single-use code valid for 30 minutes and scoped to its purpose. Re-requesting the same action replaces its earlier code. The recovery flow verifies the email address on successful completion. Verification is reported as user.email_verified_at. The API returns 503 mail_unavailable when an email-only action requires an unconfigured transport. Registration supplies a restricted session that can resend the verification email. Check the verification timestamp after the customer submits the code.
Authenticator after email confirmation
After email confirmation, the website opens the authenticator QR screen at /two-factor. A time-based setup key is available for manual entry. Confirm one six-digit code in the authenticator app, then save the eight one-use recovery codes. The website requires a fresh authenticator code on subsequent sign-ins. A password reset by email retains the enrolled authenticator.
Interactive API sign-ins receive a restricted bearer. With that bearer, POST /auth/two-factor/setup returns data.next. Values are verify_email, sign_in_again, enrol_authenticator and challenge_authenticator. For enrolment only it also returns the private uri and manual_key. POST /auth/two-factor/confirm with factor_code and replace your old bearer with data.access_token. On new enrolment the response also contains the recovery codes. Keep all of these fields out of logs and URLs. Five rejected codes within five minutes trigger an account-wide cooldown.
If the authenticator is lost, sign in with the password, then submit one unused recovery code with recover:true. Use the returned restricted bearer to enrol a replacement device and save its new recovery codes. Existing factors stay active until the replacement is confirmed. A forgotten password, email verification or a client pairing token cannot complete the second factor. Pre-existing website sessions must sign in again and older API keys must be reissued from the verified account. Paired clients use their own device authentication.
API keys for integrations
Use an account session to create an integration key.
POST /api/v1/account/tokens
Authorization: Bearer <session>
Content-Type: application/json
{"name":"customer portal","abilities":["orders:read","orders:write","registrants:read"],"expires_in_days":90}
The 201 response contains data.access_token, returned once. The server stores only its digest. Allowed abilities are account:read, orders:read, orders:write, registrants:read and registrants:write. Choose a lifetime of 1 to 365 days (default 90). An integration key cannot manage keys, change account credentials or promote its own scopes. A session can list active sessions and keys via GET /account/tokens, or revoke any of its own with DELETE /account/tokens/{id} (204). Rotate by issuing a replacement, testing it, and revoking its predecessor.
Registrant directory
Create a profile for the intended registrant. Store its returned integer data.id for use as registrant_profile_id when placing a backorder. The account owner's identity and the intended registrant can differ.
POST /api/v1/registrant-profiles
Authorization: Bearer <session-or-key-with-registrants:write>
Content-Type: application/json
{
"name": "Example Trading Ltd",
"organisation": "Example Trading Ltd",
"email": "domains@example.test",
"address_line1": "1 Example Road",
"city": "Oxford",
"postal_code": "OX1 1AA",
"country_code": "GB",
"phone": "+441865555010"
}
Required fields are name, email, address_line1, city, postal_code, a two-letter country_code, and phone with a plus sign followed by international digits. organisation, address_line2 and region are optional.
| Method and path | Key ability | Result |
|---|---|---|
GET /registrant-profiles |
registrants:read |
Active profiles for this account |
POST /registrant-profiles |
registrants:write |
201 with new profile |
GET /registrant-profiles/{id} |
registrants:read |
200 with profile |
PATCH /registrant-profiles/{id} |
registrants:write |
200 with updated profile. Supply only changed fields. |
DELETE /registrant-profiles/{id} |
registrants:write |
204. Archives the profile and clears it as the default. |
The token and profile list endpoints accept page and per_page (1 to 100, default 50), with meta.has_more for pagination. A profile belonging to a different account returns 404. A missing or expired bearer returns 401. A key without the required ability returns 403. Validation failures return 422 with field errors. Repeated authentication and mail requests are rate-limited and may return 429.
Drop catalogue API
Use the public calendar to find scheduled releases. All timestamps are in UTC. Look up the exact name to check whether a reservation is open. An absent or elapsed name has no verifiable current registration status in this feed.
| Endpoint | Description |
|---|---|
GET /api/v1/drops-meta |
Current snapshot ID, SHA-256, number of source rows, original publication time, import time, freshness deadline and stale flag. |
GET /api/v1/drops |
Keyset-paginated list in drop time and domain order. Accepts date=YYYY-MM-DD, literal domain prefix, status=upcoming|confirmed|provisional|elapsed|all, and limit=1..100 (default 50). Send the returned next_cursor as cursor with the same filters. A 409 snapshot_changed means start again on the new catalogue. |
GET /api/v1/drops/{domain} |
Case-insensitive exact lookup, with or without the final dot. Includes domain, release_id, drop_at, status, supported, source_stale, bookable (calendar eligibility), reserved_here and available_for_backorder. Reservations are enforced in the order transaction. No holder identity is returned. |
The list shows public calendar eligibility. The exact lookup additionally checks local reservation availability at request time. Service eligibility covers ordinary direct .uk and .co.uk releases. A positive availability lookup does not hold the domain. Another eligible order may be accepted before the caller orders it.
- confirmed means the future release time was within five days of the verified source publication. A new daily list can move a provisional event into that window.
- provisional means the registry lists a projected release outside its confirmed window.
- elapsed means the published release time passed, or the next publication removed the name after its scheduled release. The catalogue cannot determine who registered the name after release.
- withdrawn means a later publication omitted the name before its release time.
- unlisted means the name is absent and the catalogue has no recent departure record. Removal records are kept for 90 days.
- catalogue_unavailable and HTTP 503 mean no verified snapshot has been published. Once the source passes the freshness deadline in
fresh_until, the snapshot remains readable and new reservations pause.
Release identity and publication
Nominet publishes the source file daily. DropSnare checks the registry checksum and publishes the new snapshot once validation completes. A failed import leaves the previous snapshot available. Use the timestamp in source_published_at to tell which edition you are reading. Nominet drop list specification
A continuously listed name keeps its release ID through a time correction while its registry object identifier stays the same. A disappearance followed by relisting, or a change of registry object identifier, starts a new release. An existing reservation does not roll forward to a new release ID.
Placing a backorder
A DropSnare backorder reserves one position in this service for one release of a domain. The first eligible request accepted by the service gets the place. A receipt confirms your reservation. It carries no registry charge.
Before booking
Complete registrar onboarding and create a registrant profile, then look up the exact domain in the drop catalogue. Bookings are available for ordinary direct .uk and .co.uk names in the current confirmed release window. Save the returned release_id if you want to protect the request against the start of a later release cycle. Times are UTC. Each bearer token needs orders:write to create or cancel an order and orders:read to retrieve it.
Reserve the name
Send POST /api/v1/backorders with Content-Type: application/json, Authorization: Bearer <token> and an Idempotency-Key unique to this order. Keys can contain 1 to 128 ASCII letters, digits, periods, colons, underscores and hyphens.
{
"domain": "example.co.uk",
"registrant_profile_id": 42
}
You may add a 64-character release_id from the catalogue. Omit registrant_profile_id to use your account’s default profile. The profile must be active and belong to your account. DropSnare snapshots the chosen registrant details when it accepts the order.
A first acceptance returns 201 Created, the resource path in Location, and a JSON object under data. The receipt contains its public order ID, domain, release ID, profile ID, acceptance sequence, acceptance timestamp, scheduled release time at acceptance and status: reserved. Uppercase domain letters and one trailing DNS root dot are normalised.
Retrying the same intent with the same key returns 200 OK, Idempotency-Replayed: true, and the original receipt even after cancellation, profile edits or a schedule change. The replay response omits the creation-only Location header. Retrieve the order at GET /api/v1/backorders/{id} for its current state. Reusing a key for different input returns 409 idempotency_key_reused. Only successful reservations consume a key. A failed availability check or validation error can be corrected and submitted again.
Source tag and receiving tag
The order uses your verified default tag. Supply source_tag to select another eligible tag on your account. Set destination_tag to a tag in the current Nominet directory if another registrar will receive the domain. The default destination is the source tag. The receipt freezes both tags and the verified registry contact at acceptance. A subsequent change of contact, suspension, or lost eligibility holds execution. The registrant profile records the intended holder. A tag handover keeps the holder unchanged.
Order details include dispatch_status, registry_verified_at and handover_status when available. A client-reported catch is recorded immediately. A registrar can require an incoming transfer to be accepted before it completes. A create permit closes cancellation even if its outcome is still pending.
Read and cancel
| Request | Behaviour |
|---|---|
GET /api/v1/backorders |
Lists your orders newest first. Use limit from 1 to 100 (default 25) and pass the previous page’s meta.next_cursor as cursor. A null cursor marks the end. |
GET /api/v1/backorders/{order} |
Returns the acceptance receipt plus current status, latest known drop time, cancellation timestamp and whether cancellation is currently allowed. |
POST /api/v1/backorders/{order}/cancel |
Releases your reservation while the verified calendar still shows an open release. Another customer can then reserve it. Repeating an already-completed cancellation returns the cancelled order. |
An authenticated customer receives the same 404 for an unknown order and an order owned by somebody else. A fresh request for an active reservation returns 409 already_reserved without identifying the other customer.
Status and errors
reservedmeans the reservation holds the release.provisionalmeans the calendar moved this release outside its confirmed window. The original position remains attached to the release.cancelledconfirms the customer released the reservation.withdrawnmeans the calendar recorded the release being withdrawn.supersededmeans the same domain now has a different release identity.unlistedmeans the current catalogue can no longer identify the earlier release.window_endedmeans the scheduled release time passed. The order API does not infer a catch or loss from that timestamp.catalogue_unavailablemeans the service cannot currently verify the status or cutoff. A stale or unavailable calendar stops new bookings. If cancellation cannot be confirmed safely, the API returns503and leaves the existing receipt intact.409 release_changedmeans the caller's expected release ID no longer matches.409 release_not_bookablecovers unsupported namespaces, absent names and releases outside the confirmed window.409 active_order_limitmeans the account's active maximum is reached. The default maximum is 25 and can be configured by the operator.403 registrar_ineligiblemeans the selected tag or account cannot currently book. Check registrar setup for outstanding requirements.422 registrant_profile_requiredmeans the requested or default profile is unavailable to this account.403 email_verification_requiredapplies when the operator has enabled verification for booking.
The drop time recorded on the creation receipt remains available in accepted_drop_at. The live order's drop_at follows corrections to the same release. Once the calendar records a later cycle with a new release ID, booking that cycle requires a new order.
Let a customer use the API
In Account → API access, select a customer’s registrant profile and give the key order permissions. The registrar can also issue the key with POST /account/tokens, passing customer_profile_id and orders:read or orders:write. The customer uses the usual backorder endpoints and their own idempotency keys. Their profile and tag routing are fixed. A replacement key bound to the same profile can read that customer's delegated orders. Previous registrar-only orders and other customers' receipts stay private. The registrar retains access to every order and can revoke any customer key.
Sponsor one order
On the website, open a confirmed release and choose Offer to catch for another registrar. Select your catching tag, enter the recipient’s tag and set the maximum registry cost in pounds. Open Catch requests → Manage sponsorship offers to see offers you sent or received and withdraw an outgoing offer before a registration permit is issued.
A connected registrar can offer to perform one registration for another eligible member using the same independently verified Nominet registry account, approved allowance and contact. Each release can issue one create permit. The operator must record the actual common registry identity when reviewing both tags. Registry caps and both members’ allocations still apply. Increasing membership does not increase the common registry allowance.
- The sponsor uses a registrar session to send
POST /account/sponsorshipswithsource_tag,beneficiary_tag,domain,release_idandmax_cost_pence. A matching repeat returns the original offer. No place in the backorder queue is reserved by an offer. - The beneficiary reads incoming offers at
GET /account/sponsorshipsand accepts one with their backorder, including the offer’ssponsorship_id, exactrelease_idandmax_cost_pence. The website also shows relevant offers on the domain’s booking form. First accepted reservation wins. The beneficiary’s tag is the default destination. - The receipt fixes the source, beneficiary, destination and maximum authorised registry charge. Both members must remain eligible for execution. The sponsor can withdraw the offer with
DELETE /account/sponsorships/{id}before permit issuance. The beneficiary can cancel under the normal cancellation rules. There is no automatic reassignment. - After a confirmed catch, the registrar that paid Nominet can be reimbursed for the standard registration fee shown on its invoice, up to the accepted spending limit. DropSnare charges no service fee.
Invoice details and fallback cards
These endpoints require a signed-in member's session bearer token. Send billing requests to the dedicated API origin. Integrations open the Stripe Checkout link returned by the API. On the DropSnare website, members can enter a card directly in onboarding or Billing. In both flows Stripe receives the card number and security code.
| Method and path | Result |
|---|---|
GET /billing/profile |
Your billing details, the current invoice agreement, version, date accepted and readiness. |
PUT /billing/profile |
Save invoice details and accept the current agreement. Repeating the same request preserves the original acceptance date. |
GET /billing/card |
Masked active card, expiry flag, pending setup or removal and the current fallback agreement. |
POST /billing/card/setups |
Record consent and enqueue a Stripe setup. Supply an Idempotency-Key, card_consent: true and the current terms_version from the preceding endpoint. |
GET /billing/card/setups/{reference} |
Read a setup. Open its HTTPS checkout_url when available. The card becomes active after Stripe confirms reuse and ownership. |
DELETE /billing/card/{reference} |
Immediately withdraw consent for that setup. Provider detachment runs on the website host. |
GET /billing/card/collections |
Your previously notified fallback payments, their invoice references, amounts in GBP pence, dates in UTC and current states. Use the returned next_page as page. |
For PUT /billing/profile, send account_role (registrar or customer), payer_type (business or individual), legal_name, billing_email, address_line1, city, country_code, terms_version and terms_accepted: true. A UK address also requires postal_code. Optional fields include address_line2, region, tax_reference, purchase_order and a billing reference tag for registrars. Registrar authority is established separately in onboarding.
A new or pending setup returns HTTP 202 and a Location to poll. Use a key of 1 to 128 ASCII letters, numbers, periods, underscores, hyphens or colons. The website worker runs every minute. Poll the setup at one-minute intervals while the checkout URL is pending. The URL is private to this setup. An integration can poll again after the member enters their details, even if the member closes the browser before the normal website return. Repeating the initial request with the same key returns the original setup, including after replacement or revocation.
Statements awaiting verified bank instructions have no payment due date and cannot trigger a fallback notice or collection.
DropSnare charges no service fee. A successful catch costs the standard Nominet registration fee. Monthly invoices are payable by bank transfer. A saved card authorises fallback for the outstanding balance after its due date. Advance notice identifies the exact amount, card and collection date. A changed amount or a replacement card needs fresh notice. The billing screen and API show notice and collection history. bank_payment_required or declined means the member should pay the invoice by bank transfer. A card payment still being reconciled appears as processing. Actual overpayments appear as member credit.
Monthly statements and withdrawals
DropSnare is free. You pay only Nominet’s standard registration fee for a domain caught for you. Each month your GBP statement shows those fees, what you paid Nominet on behalf of other members and the balance. Months close in UTC.
When you fund your own order, the same cost appears on both sides and your net contribution is zero. When a registrar explicitly sponsors your order, its recorded spending ceiling limits the total. The cost belongs to the ordering account and the reimbursement belongs to the registrar that paid the registry.
Read your billing account
All routes here require your account session bearer. Integration keys and paired devices cannot access invoices or withdrawals.
| Request | Result |
|---|---|
GET /account/billing |
Outstanding payable contributions, contributions awaiting bank instructions, reimbursement balance, cleared credit available to withdraw and pending withdrawals, all in GBP pence. |
GET /account/billing/statements |
Up to 50 summaries, newest first. Pass the returned next_cursor as cursor for the next page. |
GET /account/billing/statements/{reference} |
Captured billing details, issued bank instructions where applicable and up to 100 lines showing your costs and advances. For more lines pass next_line_cursor as cursor. |
GET /account/billing/withdrawals |
Your recent bank reimbursement requests. Pass next_cursor back as before to continue. |
POST /account/billing/withdrawals |
Reserve cleared credit for reimbursement to your own UK bank account. |
awaiting_bank_instructions means your month is calculated and payment is pending bank setup. A positive invoice becomes payable when verified business receiving details are configured. The due date starts on issue. You can read the invoice in Billing and the billing contact receives a notice. Use the unique invoice reference on your transfer. historical preserves statements created before itemised settlement. A recorded historical balance has no authority to start a card collection.
Cleared bank or fallback card receipts reduce the original invoice. Excess actual payments stay as credit. Member reimbursements clear as money settles for the same month. Unused cleared credit offsets eligible unpaid invoices and the remainder is available for withdrawal. Each allocation has an audit entry. A credit can be reserved for a withdrawal once. A cancelled, unsent transfer returns that reservation to the balance.
Request a bank reimbursement
Send an Idempotency-Key with one to 128 ASCII letters, digits, dots, underscores, colons or hyphens. Supply a positive integer amount_pence, your current password, the payee from your billing profile, a six-digit UK sort_code and eight-digit account_number. A verified account email is required. Keep the same key and payee details on a retry. A changed request using the same key returns 409. Bank details are encrypted and only the reference, amount and status appear in your history.
requested reserves the amount. prepared means the payee was independently verified and an instruction prepared. paid requires the actual outgoing bank transaction. A reference can settle one withdrawal. Member bank transfers and verified registry charges carry no DropSnare fee.
Registrar device protocol
All routes below use the /api/v1/client prefix and UTC timestamps. Device traffic goes to the API hostname over HTTPS. Members approve each computer in their browser. Nominet credentials stay on the registrar's device. The service has one authoritative account, order, quota and release ledger.
Connect a PHP or Mac client
The installer and installed client use the same approval screen. Members enter their account password and authenticator codes only on the website. The client receives the browser’s approval through the API. The API issues a separate device credential scoped to the approved registrar tag.
- Send
POST /authorizationswithname,platform(phpormacos) andmode: "install"from the installer. A manually downloaded client usesmode: "link"and includes its signed release’sversionand integerbuild. - A 201 response contains
verification_uri,user_code,device_code,expires_in(600 seconds) andinterval(5 seconds). Display the fixed website address and eight-character user code. Keep the privatedevice_codein process memory or briefly in an owner-readable installation file. Keep it out of URLs, argv and logs. - The member goes to
https://dropsnare.co.uk/connect-device, verifies their email, completes authenticator setup or signs in with their existing authenticator, and completes the registrar profile if needed. They enter the code from their computer, check the computer name and code, select their registrar tag, then approve or decline. - Send
POST /authorizations/tokenwith the privatedevice_codeandphase. A 202 withdata.status: "pending"means to continue polling. Respect the interval and HTTP 429Retry-After. A 403 ends the attempt. A 410 means this code or build can no longer be used. The user can start a fresh connection. - For an installation, start with
phase: "download". After approval, the 200 response includesdata.buildand a short-liveddata.ticket. POST the ticket to the existing manifest and package endpoints. Verify the package with the trusted signing key before starting it. An interrupted download can request a new ticket during the ten-minute approval window. - For a manually installed client or after the installer has verified the package, use
phase: "device". Store the returned device token locally with owner-only access. This step succeeds once. A lost final response requires a fresh link. The member can revoke an unused computer from Client downloads.
Both redemptions recheck the signed release, approving account session, email and factor enrolment, billing and selected tag. Signing out before redemption invalidates the approval. The PHP and Mac releases can report diagnostics after connecting. Both releases have diagnostic access only.
Multiple computers and registry sessions
Each installation receives its own device token. A process creates a random UUID on startup and keeps it in memory. The API gives one process permission to open registry connections for the entire account. The physical tag is also exclusive across accounts. Different registrars can keep independent holders. The account's allocation and ledger apply across all of its installations.
- Check updates and report the installed build in a disconnected heartbeat. When credentials are available and the device can participate, send
POST /registry-leasewith{"protocol":1,"instance_id":"<UUID>","ready":true}. This call also authorizes the first password test during setup. An active denial, failed release verification or incomplete account prevents a grant. - With
data.role: "active", keeplease_tokenin process memory. Start the deadline at the beginning of the HTTP request using a monotonic clock that accounts for suspend, or also enforce an independent wall-clock deadline. The grant lasts at most 45 seconds. Include the time for API calls, EPP operations and socket teardown in this budget. Handle sleep/wake as lease loss. Renew with the same UUID, usually every 10 seconds. A valid uninterrupted renewal returns the same token. - Include
X-DropSnare-Leaseon registry connection and denial reports, contact provisioning, work reads, work leases, permits, handover reads and claims. Use it on a holder's disconnected heartbeat too. A standby may send an idle heartbeat, check versions and exchange diagnostics. A stale or missing fence on a privileged request returns HTTP 409. Device tokens, lease tokens and registry passwords stay out of logs and URLs. - With
standbykeep the local registry connection count at zero. Withunavailable, resolve the prerequisite or update the device. Show the current role on screen. Retry after the response'sretry_after_seconds. Stop registry activity and close sockets on lost authority, a changed generation, suspension, authentication failure, or inability to renew before the deadline. Close sockets before signallingready:false. A clean release invalidates the old token immediately. - A healthy incumbent retains the grant. Ordinary polling, opening the app on another Mac and new sign-ins leave it in place. The server reserves a further 15 seconds after the last server expiry before any takeover, including on snooze and revocation. With timestamp rounding this can be 61 seconds from the last grant, plus polling time. The latest eligible ready check-in in the prior 30 seconds wins among standbys of equivalent capability. Work-capable candidates take precedence on failover. Offline, revoked, outdated and blocked devices cannot win. A new generation requires a fresh registry login and heartbeat.
- A permit can be issued only once. Losing the responding process or losing the response cannot cause another device to repeat a create. The issuing device can report an existing result after failover. A claimed transfer can likewise receive its original receipt. If a contact operation completed at the registry before disconnection, the original device may send its receipt with the fence used to fetch that contact. For other cases reconcile the registry evidence. Receiving a lease alone never authorizes a create or transfer.
PHP builds below 4 and macOS builds below 2 predate this protocol. An unexpired, linked legacy installation in the same account or on the same tag blocks new grants until it upgrades. For a retired installation stop the old software before unlinking it. Deploy the migration and fenced API before publishing the signed clients. The API cannot close registry sockets opened directly by old software. The published PHP and Mac clients have diagnostic access only. The devices API exposes the registry role in catch_role; display registry login and work capability separately.
Mac diagnostics
The Mac sends its release and connection state on authenticated heartbeats. Once an hour it sends integer counters with PUT /diagnostics/summary. These include check-ins, errors, registry logins, requests seen, attempts and catches. Clients can also report a count of confirmed transfers. Optional API and registry response times use milliseconds. Counters describe observed behaviour and have no effect on orders or charges. Retrying a summary replaces the same device's UTC hour. The server accepts up to 48 hours of backfill and retains 30 days.
Detailed events stay on the computer for up to seven days. A Mac receives a device-specific support request in the next heartbeat under data.diagnostic_request. It contains id, since, expires_at, max_records and max_bytes. Use PUT /diagnostics/requests/{id} with {"events":[{"at":1794895200,"code":"registry_error"}]}. The member can disable detailed sharing in the app, which replies with {"declined":true}. The server accepts up to 512 events and 128 KiB in one request. Each event has a UTC Unix timestamp, a known event code and an optional integer value. For registry_rtt the value is the measured round-trip time in milliseconds. Credentials, contact details, domains and free-text log lines are excluded. The server retains requests and uploads for seven days. Detailed reports are available to operators on the API host.
Pair an older client
- Complete the website profile and open Client downloads. This requires a verified email, a listed tag, a saved default contact, the required allocation, billing details and an active fallback card. Once a client is published for your platform, install it and generate a one-use pairing code for your tag. A fresh code replaces any unused code for the same account and tag. Codes expire after ten minutes.
- Send
POST /pairwith the code, a device name, a platform (php,windows,macosorlinux), the installed version and a positive integer build. The response contains the bearer token once. Store it in the OS credential store or a file readable only by the client service account. - Send
Authorization: Bearer <device token>on every subsequent request. A token belongs to one account, source tag, device and platform. It expires in 90 days. Re-pair and revoke the old device from registrar setup when replacing a machine or renewing credentials. - Send
GET /statusfor account eligibility and individual reasons. The API rechecks the selected tag when exchanging the code. A newly paired device can submit its first connection report immediately. Work requires a fresh connected report from the requesting device. Existing devices can report a disconnect, registry denial or restoration while account checks are pending.
Pairing and status return observed_ip when the API sees a public address. This is the device’s egress to DropSnare. Nominet may see a different address on a network with separate routes.
Report connection and capacity
Send POST /heartbeat at the interval in the rules response and immediately on disconnect. After the registrar authenticates to Nominet, include the registry environment, the tag used for the login and the successful login’s server transaction ID (svTRID). Repeat those three fields while that session remains connected. On reconnect, use the new login’s transaction ID. A connected report expires after 90 seconds. Report a fresh heartbeat after a client update.
{
"connected": true,
"active_connections": 1,
"registry_environment": "production",
"authenticated_tag": "EXAMPLE-TAG",
"login_reference": "EXAMPLE-LOGIN-1234",
"external_connections": 0,
"external_creates_24h": 2,
"version": "1.0.0",
"build": 1,
"rtt_ms": 28,
"clock_offset_ms": 3
}
active_connections counts this device's current DropSnare registry sessions. Set it to zero on disconnect. Both external counters cover the whole Nominet registrar account across all its tags and tools. Exclude activity already tracked by DropSnare. Supply zero only when the registrar knows the actual amount is zero. Use null or omit the counters if the totals are unknown. That device then receives no work. The server takes the highest fresh external observations, adds its own usage and checks both the member allocation and the shared registrar-account limits. Only round-trip time and clock offset are accepted as optional timing diagnostics.
Create permits consume one unit of the rolling 24-hour service allowance at issue time, including when a response is lost. This is a capacity ledger. It does not produce an invoice or tell the registrar that Nominet charged for a command. A pending or unknown result also occupies a connection slot until resolved.
Set up the default contact
After a successful production login with the paired tag, the client can submit the contact the member saved during onboarding. Credentials stay on the device. Send only the specified fields to DropSnare and keep the returned contact details out of application logs.
- Call
GET /registration-contacton the device paired to the member’s default tag, with a fresh production login heartbeat. The response gives the tag, contact handle and status. If the status isreportedorverified, contact submission is complete for this handle. Withcreate_or_confirm,epp_requestcontains the prepared EPP contact request when the member has saved contact details. A legacy handle with no saved details returnsepp_request: nulland allows confirmation of an existing contact only. - Through the authenticated Nominet session, check whether the handle already exists. If the registry confirms it is absent and a prepared request is available, submit that request once. For an existing handle, confirm that the sponsoring tag and contact details match the prepared contact. If ownership or details differ, stop without modifying the registry record. After a timeout or interrupted session, look up the handle through the registry before retrying a create.
- Send
PUT /registration-contact/receiptwithtag,handle,operationandregistry_reference. Usecreatedwith the successful create’s server transaction ID orconfirmed_existingwith the successful contact lookup’s server transaction ID. Retain the matching receipt securely until DropSnare acknowledges it. Recheck the saved contact if the member changes it.
reported means DropSnare has the device’s registry receipt. verified means DropSnare has independent evidence for the current contact. A login and a contact receipt alone cannot establish domain-create permission, the registry account linking several tags or its available capacity. The service checks those independently before admitting work. Nominet EPP commands
Discover and complete an order
| Endpoint | Client behaviour |
|---|---|
GET /work |
Read up to 50 eligible reservations assigned to the paired account and tag, earliest release first. Follow poll_seconds and send the previous ETag in If-None-Match. A policy change returns 200 even if the assignments and budget are unchanged. Fetch /rules when policy_revision differs from the cached revision. |
POST /orders/{order}/lease |
Obtain the exclusive 60-second lease for this device. Retrying before expiry returns the same lease. An expired preview can be reclaimed if the order is still active. |
POST /leases/{lease}/permit |
Request a single-create permit after the current scheduled release. A 200 response includes the immutable domain, source, destination, verified contact and a three-second expiry. Persist the lease transition before dispatching locally. |
GET /leases/{lease} |
Read whether a permit was ever issued and the current outcome. Use after a timeout, restart or ambiguous response. This endpoint provides no authority to send or resend a command. |
PUT /leases/{lease}/result |
Submit caught, missed, not_sent or unknown. Include a non-secret registry_reference for a catch. Identical retries are idempotent. An unknown can be replaced with a conclusive result. |
A lease can be issued before the release for preparation. A work listing or lease alone never authorises a create. The server rechecks the active daily catalogue, time, release identity, cancellation, source contact, destination, member permissions, device, card, capacity and update policy when issuing the permit. The same release can have at most one issued permit. By default the registrar that booked the order executes it. A linked registrar may execute a single explicitly sponsored reservation under the same independently verified registry account and contact. Every release still has one create permit. Both accounts must remain eligible.
If a permit request times out, query its status. If it was issued, treat delivery or execution as uncertain, record what the device actually knows, and reconcile using the registry record. A lost 200, an expired permit, a reboot or a disconnected session never justifies a second create. If the lease is still offered, the client can request its first permit while the lease and the order remain valid. Devices must also stop locally if the registry session, remaining live capacity or authority changes before sending.
A client may report a previously issued result after billing suspension or a mandatory update. If the device token has expired or was revoked, operations staff can record the outcome from independent registry evidence.
Registry access and limits
A paired device that receives a registry block or a create-permission denial includes registry_denial of registry_blocked or create_denied in its next heartbeat. DropSnare places the independently verified registry account on hold across its linked tags. Stop sending registry creates immediately on the device. A subsequent successful login or heartbeat leaves the hold in place. Staff record independent evidence of restored access before clearing it.
The service enforces six concurrent EPP sessions per tag. Include external_tag_connections when local tools know the total external connections on this tag. Omitting the field makes the service apply the external count for the whole registry account conservatively. The combined ceiling on EPP and Web Domain Manager creates against already registered names is 1,000 per linked registrar in a rolling 24 hours. DropSnare counts all issued permits and reported external creates towards that maximum, and enforces lower verified and member limits. Each verified registry-account identifier must represent the full set of tags Nominet links for these limits. Nominet acceptable use policies
Record a handover
A reported catch immediately creates a durable handover record for the destination chosen on the order. It begins at verification_pending. After independent confirmation, a catch on its intended tag becomes same_tag. A confirmed catch with a different destination becomes pending_handover.
GET /handovers lists outstanding cross-tag handovers for an eligible connected source registrar. Follow the returned next_after with ?after= to read further pages, and restart from the first page on the next scan. Both handover queues accept a saved ETag in If-None-Match and return 304 when the page is unchanged. Each item specifies the recorded source and destination, a zero fee ceiling, and an unchanged registrant. The destination must still be in the current registrar directory. A suspended registrar or paused service cannot receive actionable handover records.
Only the process holding the current registry lease can read the review queue. Its entries are instructions for the registrar reviewing the case and provide no permission to perform an automated registry release. For a pending release, first submit POST /handovers/{order}/claim with {"direction":"outgoing"}. One device can claim the outward change. If the response is lost, reconcile the registry record before acting. Each response lists the domain, bound tags and a maximum fee of zero. For each pending item, the registrar checks its authorised registry channel, receiver handshake requirements and fee treatment before acting. If zero cost and unchanged registrant cannot be established, hold the item for review. The API does not execute EPP, select a paid alternative, or treat a transfer request as receipt by the destination.
A source device can report a submission it has already made using PUT /handovers/{order}/submission. Supply the exact domain, source_tag, destination_tag, a non-secret registry_reference, and boolean true for zero_fee and registrant_unchanged. A matching receipt returns the existing state. A conflicting reference or destination is rejected. The intermediate state submission_reported records the device's assertion. Operations staff use independent registry evidence to establish awaiting_acceptance or final completed. A source client must reconcile these intermediate states against the registry before taking another action.
A device with a valid token can report a handover it already claimed after the account is suspended, the registry disconnects, the service is paused or a new build is published. This applies in either direction. A late receipt preserves any subsequent state independently confirmed by staff. A revoked or expired device must refer its evidence to operations.
A participating receiver checks GET /handovers/incoming. Only the independently verified destination tag sees its pending handovers after staff verify the registry’s pending handshake. A receiver gets an exclusive claim with POST /handovers/{order}/claim and {"direction":"incoming"}. Match the pending registry change, domain, source, destination and unchanged holder, and stop if any fee applies or permission changes. After accepting at Nominet, send PUT /handovers/{order}/acceptance using the same fields as the outgoing submission receipt. The device’s acceptance_reported state awaits independent confirmation. A missing response to a claim leaves the action reserved for registry reconciliation. Repeating a receipt with the identical reference is safe. A destination outside DropSnare uses its normal registrar acceptance procedure.
Operational recovery
The following commands run on the application host with trusted operator access. Evidence references identify restricted registrar records or case IDs. Never include passwords, contact details, access tokens or raw registry exchanges.
php artisan client:review --limit=50
php artisan client:resolve LEASE_ID caught --evidence=REGISTRY-CASE-ID
php artisan client:handover LEASE_ID --awaiting-acceptance --zero-fee --evidence=SUBMISSION-CASE-ID
php artisan client:handover LEASE_ID --zero-fee --evidence=ACCEPTANCE-CASE-ID
Use --after=ID on the review command to continue paging. Confirm the release identity, order, sponsoring tag and registrant against the registry evidence. For completion also verify the named receiving tag now holds the domain and the registrar transfer charge was zero. Result and confirmation writes are idempotent with the same evidence. Account suspension retains the original record for investigation.
The platform-specific update manifest and package endpoints are documented in the client update guide. An API upgrade response blocks new assignments while allowing update downloads, eligibility checks and recovery of prior results. On 429, honour Retry-After. On 503, back off and retain pending receipts locally. The first client implementation must follow the signed-update and durable single-permit rules before production enrolment.
Client updates and service policy
Authenticated devices use the platform selected during pairing. The supported platform identifiers are php, windows, macos and linux. The release channel is stable. Build numbers are positive, increasing integers scoped to a platform. A display version such as 1.0.2 accompanies each build.
| Method and path | Result |
|---|---|
GET /api/v1/client/updates |
The installed build reported at pairing or in the last heartbeat, newest signed build for that platform, minimum build, update interval, signed envelope and relative package path. latest_build, release and package_path are null until the first release. |
GET /api/v1/client/updates/{build}/package |
Authenticated binary download of the current signed build for this device's platform. A superseded build returns 410. An unpublished channel returns 404. |
GET /api/v1/client/rules |
The current policy revision, work switch and recommended update/work polling and heartbeat intervals in seconds. |
Use the device bearer token for these requests. Send the last response's ETag back as If-None-Match on updates and rules. HTTP 304 retains the previous representation. Store responses per paired device, platform and origin. The initial work and update polling interval is 15 seconds. Work polls and heartbeats include policy_revision, so a device with the current rules can skip a separate rules request. Stagger polls when several devices reconnect. Apply the latest interval from the response. Honour Retry-After following throttling and back off after network failures.
Before accepting work, check the published build. Every new signed build supersedes the previous build. New work on an older build returns HTTP 426 with error.code=client_update_required. A future build or a display version that differs from the signed manifest for the current build returns 409. An unpublished production channel returns 503. The service still accepts update checks and recovery reports for work already started. Build and connection reports are device declarations.
The update response contains a release object with three strings:
| Field | Representation |
|---|---|
key_id |
Lowercase hexadecimal SHA-256 fingerprint of the raw Ed25519 public key. |
payload |
Standard base64 encoding of the exact UTF-8 JSON bytes covered by the signature. |
signature |
Standard base64 encoding of the 64-byte detached Ed25519 signature over the decoded payload bytes. |
A client verifying an update must select a public key embedded in its trusted installation by the reported fingerprint. Verify the signature over the decoded bytes before parsing the JSON. Check schema=dropsnare.client-release.v1, platform, monotonic build, display version, lowercase sha256 and bytes. Verify length and SHA-256 of the entire download before installation. A build number must identify one immutable package. Reject a lower build than the installed build or the greatest verified build previously seen, and reject a changed signed payload for an already known build. Use HTTPS on the configured API origin. A package URL is a relative path on that origin.
An updater should save the last reported attempt durably, finish or reconcile already-started work, stage the verified package, atomically switch installations and restart. Report the running build in the heartbeat after restart. If installation or verification fails, retain the last usable installation, report the problem through the client and keep new work paused. The server publishes bytes and enforces reported versions. The PHP installer and updater verify the release on the device.
The current policy also includes lookahead_minutes and late_seconds. These govern how early an order can appear and when its permit window closes. The API rechecks the current policy before granting a permit.
First installation
The member reaches Client downloads after completing their website profile, including email verification, authenticator enrolment, listed tag, default contact, resource allocation, invoice details and fallback card. Each of the four platforms shows its publication status. The PHP preview offers a terminal setup and a local dashboard. The Mac entry offers the signed ZIP and a Terminal installer when the channel has a signed release. Windows and Linux have their own release channels.
GET /api/v1/account/registrar/installers accepts the member’s session bearer and returns five-minute tickets for published builds. Each ticket belongs to one platform, build and account session. POST the ticket to the returned manifest_url or package_url on the API origin as a form body or JSON object. The origin rechecks the session, the member’s access to installation media and the current signed release. Verify the signature and digest with the public key embedded in the installer.
For PHP, copy the installation command from Downloads. It verifies the bootstrap SHA-256 before execution. The computer displays a short code. Enter that code at DropSnare device sign-in, complete the website’s account checks and approve the computer and tag. The installer fetches the signed package and hands the approval to the verified client through a private pipe. Manual installation is available in the Downloads disclosure. Verify the displayed digest and start setup. Both paths use the same website approval. The PHP client collects the Nominet EPP password locally after approval.
A connected diagnostics device can report its health. The production service requires a work-enabled platform to place bookings or obtain registry work. A connected diagnostics-only account receives the eligibility reason work_client_required. Pairing and contact setup
For macOS the website pins the SHA-256 of GET /api/v1/client/installers/macos/bootstrap in the copyable Terminal command. It also supplies the expected build and ZIP digest. Manual downloads use a session-bound POST and the same signed package bytes. Downloaded apps are distributed directly by DropSnare. A Mac installed from the ZIP uses the same website device approval as the terminal installation.
Installation feedback
Report each installation attempt with PUT /api/v1/client/updates/{build}/reports/{attempt} using the device bearer. Generate a UUID for the attempt and save it before starting. For a successful restart, send the running build and version in a heartbeat first, then send {"outcome":"installed"}. For a failure, send {"outcome":"failed","failure":"digest_mismatch"}. The permitted reasons are download_failed, signature_invalid, digest_mismatch, installation_failed, restart_failed and rollback. Replaying the same receipt returns the original timestamp. New attempts take a new UUID. The member can inspect its devices, current connections and most recent update reports via GET /api/v1/account/registrar/devices, using next_after as the next page’s after value.