Authentication, API keys and resource tokens

Which credential do I need?

socket.help has two kinds of credentials. Account credentials (an API key or a signed-in browser session) identify your workspace. Resource tokens are returned when a resource is created and control one resource: either managing it or calling it.

Most endpoints also work without any credential. Anonymous requests use the anonymous plan, and their usage is tracked by a hashed IP address, so people on the same connection share limits.

API keys

Create keys in your workspace’s API keys section at /account/. A key is shown once at creation; the server stores only a hash. Each key belongs to one user and one workspace, and requests made with it use that workspace’s plan and allowances.

Key creation, listing and revocation (GET, POST /api/account/keys and DELETE /api/account/keys/{id}) require a signed-in browser session, so a key cannot create or revoke keys. Keys also cannot change workspace membership or open billing sessions.

• Expiry: 1 to 365 days, 90 days by default.
• Up to 20 active keys per user and workspace.
• An invalid, expired or revoked key returns 401. The request does not fall back to anonymous access.
• Resetting your password revokes all sessions and API keys. Workspace resources are kept.

curl https://socket.help/api/account \
  -H "Authorization: Bearer $SOCKET_HELP_API_KEY"

Scopes

A key can hold any of four scopes. By default a new key receives every scope your workspace role allows; you can choose fewer when you create it. A request outside the key’s scopes returns 403.

Workspaces and roles

Every account has a personal workspace. Team workspaces can add members with the roles owner, admin, member or viewer. The role limits which scopes a key or session can use.

• Owner: every scope.
• Admin and member in a Team workspace: every scope.
• Viewer in a Team workspace: resources:read and account:read.
• Any non-owner in a workspace that is not on the Team plan: account:read only.

Resource tokens

Anonymous resources are managed with the token returned at creation: inspectionToken for webhook inboxes and managementToken for mock APIs, files and mock MCP servers. Send it as Authorization: Bearer. If an API key already occupies the Authorization header, send the resource token in X-Resource-Token instead.

Resources created with an API key or session belong to the workspace. They are managed with current workspace access, so a leaked management token alone does not grant management of a workspace resource.

Private resources also return an accessToken. It is the only credential a webhook sender, mock API caller, MCP client or file recipient needs. It cannot read history or change the resource, and a management token cannot download a private file.

curl https://socket.help/api/mocks/MOCK_ID \
  -H "Authorization: Bearer $SOCKET_HELP_API_KEY" \
  -H "X-Resource-Token: $MANAGEMENT_TOKEN"

Browser sessions

Signing in sets a seven-day HttpOnly, SameSite=Strict session cookie. Requests that change data with a session must come from the site itself; a mismatched Origin returns 403 with a hint to use an API key for scripts.

Any /api/ request that carries an Origin header for another site is rejected with 403, so the API cannot be called from third-party web pages. Use an API key from a server, script or CI job.