API overview & authentication

The SafeHanded REST API lets you create requests, read their state, end them, and feed ticket status changes in from your own tooling. For: Integrators. Available on Team and above.

• Base URL: https://safehanded.com/api/v1
• API reference — every endpoint, with parameters, request bodies, example responses, ready-to-copy code (curl, JavaScript, Python, PHP and more) and a built-in client to try calls with your own key.
• Postman collection and OpenAPI 3.1 document — see Try it in Postman.

No endpoint returns a credential

There is no API that returns a decrypted secret — reveal is browser-only, to a recipient’s identity key. The API creates and manages requests; it never handles plaintext.

Authentication

Create a key under Settings → API (Owner/Admin). Keys look like sh_live_ followed by 43 characters; SafeHanded stores only a hash and shows the key once. Send it as a bearer token:

Authorization: Bearer sh_live_…

Each key carries:

Property	Meaning
Scopes	requests:read, requests:write, tickets:write, events:read, webhooks:write. A missing scope answers 403.
Client scope (MSP)	Optional — a client-scoped key only sees and creates for that client.
IP allowlist	Optional addresses or CIDR blocks; use from elsewhere answers 403 and is audited.
Expiry	Optional; expired or revoked keys answer 401.

Test a key with GET /ping — it returns the organisation, the key’s scopes and a connection label.

Try it in Postman

1. Download the SafeHanded Postman collection (right-click → Save link as…), then in Postman choose Import and drop the file in. Or choose Import → Link and paste https://docs.safehanded.com/safehanded-api.postman_collection.json.
2. Open the SafeHanded API collection → Variables and paste your key into apiKey. Every request uses it automatically.
3. Send Connection → Check the API key. A 200 with your organisation’s name means you’re set up.

Use a test key

For trying the API — here, in the API reference’s Test Request panel or in Postman — create a dedicated key with only the scopes you need (for example requests:read) and an expiry, and revoke it afterwards. A key typed into the API reference stays in that browser tab and isn’t saved; one pasted into a Postman variable is stored by Postman (and synced to your Postman account if you use one), so keep it in the variable’s current value only and don’t share or export the collection with it filled in.

The requests are grouped like the reference (Connection, Requests, Shares, Events, Tickets, Webhook subscriptions) and come with example bodies. POSTs send a fresh Idempotency-Key each time, so a resend creates a new request rather than replaying the last one.

Prefer to generate your own client, or use Insomnia, Bruno or another tool? Import the OpenAPI 3.1 document instead — Postman accepts it too (Import → Link, https://docs.safehanded.com/openapi.json).

Conventions

• Errors are { "message", "code" }; codes include unauthenticated, forbidden, not_found, validation_failed, conflict, rate_limited, and plan_required (403) when your plan doesn’t include the API.
• Rate limit 600 requests/minute per key, and 1,200 requests/minute across all of an organisation’s keys (X-RateLimit-*; 429 with Retry-After).
• Idempotency — send Idempotency-Key: <unique string> with a POST; the first response is stored for 24 hours and replayed for the same key and body. A replay returns the same status and Location header, but secret fields (link, link_without_fragment, challenge_code, a share’s secret/value) come back null: they are shown once, on the original response.
• Pagination — limit (≤ 100) and cursor (the previous page’s next_cursor); newest first.
• Ids are 26-character ULIDs; times are ISO-8601.

Core endpoints

Method and path	Scope	Purpose
GET /ping	any	Verify the key
POST /generate	any	Generate a strong password/passphrase (stores nothing)
POST /requests	requests:write	Create and commit a request; returns the full link
GET /requests	requests:read	List (filter by status, client_id, ticket_ref)
GET /requests/{id}	requests:read	One request
POST /requests/{id}/revoke	requests:write	Kill a live link
POST /requests/{id}/complete	requests:write	Destroy a submitted credential
POST /tickets/{ref}/status	tickets:write	Mark a ticket status (close-to-purge)
GET /events	events:read	Poll event objects
GET/POST/DELETE /webhooks	webhooks:write	Manage webhook subscriptions

The API reference has the full detail for each, including the certificate downloads.

Create a request

curl -X POST https://safehanded.com/api/v1/requests \
  -H "Authorization: Bearer sh_live_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-4411-attempt-1" \
  -d '{
    "subject_name": "Jane Doe",
    "subject_email": "jane@customer.example",
    "justification": "Password reset for ticket 4411, identity confirmed by phone.",
    "recipients": ["tech@msp.example"],
    "ticket_ref": "HD-4411",
    "ttl_minutes": 60,
    "verification_mode": "challenge",
    "delivery": { "method": "email" }
  }'

Recipients are members of your organisation, addressed by email; each must have set up an identity key (the request is encrypted to them). The 201 response contains the request, the complete link, and the challenge_code when the verification mode needs one — give the code to the subject out of band, never in the same message as the link.

Recipient commitment via the API

In the app, the technician’s browser computes the recipient commitment in the link fragment, so even the server can’t swap recipients unnoticed. Through the API there’s no browser, so SafeHanded computes it. If that distinction matters to your threat model, create those requests in the app.

Close-to-purge from any platform

POST /api/v1/tickets/HD-4411/status
{ "status": "closed" }

Where the linked adapter can read the ticket back, the status is verified against the ticket system before anything is destroyed. Requests that merely quote the ticket reference are matched too, but those are unverified and only purge when Trust unverified webhooks is enabled in Policy.

Security

• Prefer one key per integration with the smallest scopes, an IP allowlist, and an expiry.
• Every API action is audited with the key’s name; revoke a key and its callers get 401 immediately.
• Payloads never contain envelope material, link tokens, codes or key material — enforced by a test suite over every response shape.

Related

• API reference
• Webhooks
• Automation platforms