Sharing and access: public and private resources
How socket.help visibility works: private resources require an X-Access-Token, public ones accept anyone with the URL, and access tokens can be rotated.
Updated 27 October 2026Public and private
Every webhook inbox, mock API, file and mock MCP server is either public or private. Visibility controls who can use the resource’s public endpoint: send to the webhook URL, call the mock, connect to the MCP server or download the file. Management (reading history, updating, deleting) always needs the management token or workspace access, whatever the visibility.
All interfaces create private resources by default: the HTTP API, SDK, CLI, SSH gateway and MCP. Pass visibility=public explicitly when you want an endpoint that works without a credential.
| Visibility | Endpoint callers need | Management needs |
|---|---|---|
| private (default) | The access token, or workspace access for workspace resources | Management or inspection token, or workspace access |
| public | Only the URL | Management or inspection token, or workspace access |
Sending the access token
Send the access token in the X-Access-Token header, or as Authorization: Bearer when the caller has no other use for that header. Access tokens are 43-character strings returned once, at creation or rotation, and stored on the server only as hashes.
Requests with missing or wrong access get 404, so a private resource is indistinguishable from a missing one. Invalid access never captures a webhook request or uses a file download.
curl https://socket.help/mock/MOCK_ID/users/42 \
-H "X-Access-Token: $ACCESS_TOKEN"Change visibility or rotate a token
POST /api/{kind}/{id}/sharing with {"visibility":"public"} or {"visibility":"private"}, where kind is inboxes, mocks, files or mcp-servers. Authenticate with the management token (inspection token for inboxes) or workspace access.
Setting private always issues a new access token and immediately invalidates the previous one, so posting private to an already private resource rotates its token. Setting public removes the access token. Every change returns a new accessVersion.
curl -X POST https://socket.help/api/inboxes/INBOX_ID/sharing \
-H "Authorization: Bearer $INSPECTION_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"visibility":"private"}'
# 200 OK
{"visibility":"private","accessVersion":"NEW_ACCESS_VERSION","accessToken":"NEW_ACCESS_TOKEN"}Workspace access
Resources created with an API key or session belong to the workspace. Members with the right scope can use private workspace resources without the access token: resources:write to send to an inbox, resources:read to download a file or call a mock or mock MCP server. Browser sessions get this only for requests from the site itself.
Frequently asked questions
What is the default visibility?
Private, on every interface. Request public visibility explicitly with ?visibility=public on HTTP, visibility: "public" in the SDK, --visibility public in the CLI or the visibility argument in MCP tools.
How do I revoke access I already shared?
POST {"visibility":"private"} to /api/{kind}/{id}/sharing. The old access token stops working immediately and the response contains a new one. Deleting the resource also ends all access.
Does a management token let me download a private file?
No. Management and access are separate. Download a private file with its access token or with workspace credentials that have resources:read.
Why does a private resource return 404 instead of 401?
So that callers without access cannot tell whether the resource exists. Check that you are sending the current access token in X-Access-Token.