Make your first supported API request

The Protodesk Platform API lets a server-side integration work with one workspace. Start with a read-only request that confirms which workspace and permissions your key represents. This guide uses the public API at https://api.protodesk.io/v1, not Protodesk's internal /app routes.

Create a limited key

In Settings → API, create a key for the integration and select only the permissions it needs. Copy the secret when it is shown and store it in your server's secret manager. The key's Test or Live label does not create an isolated database: requests reach the actual workspace associated with that key. See Create and manage API keys.

Do not put a workspace key in browser JavaScript, a mobile app, a public repository, a URL, or an article. Keep it out of request logs and screenshots.

Check the key and workspace

Load the key into your server environment as PROTODESK_API_KEY, then make a read-only request:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${PROTODESK_API_KEY}" \
  -H 'Accept: application/json' \
  https://api.protodesk.io/v1/me

A successful 200 response contains apiKeyId, workspaceId, and scopes. Compare workspaceId with the workspace you intended to connect, and check for the exact scope required by your next operation. Stop if either is wrong. Do not log or forward the Bearer header while troubleshooting.

Make a resource request

For example, a key with customers:read can request GET /v1/customers. The list response contains data, hasMore, and nextCursor. It does not return every customer in one call; follow the returned cursor while keeping the same filters. A key without that scope receives an authorization error. Reading another workspace's data is not enabled by passing another workspace ID.

Use the public OpenAPI contract for each endpoint's current method, fields, required scope, and response. Create, update, and delete requests can affect real workspace data. Before adding writes, decide how your integration will handle retries and reconcile an uncertain outcome. See Handle API errors, pagination, retries, and realtime events.

The Help Center authoring API, public Help Center reads, and customer Chat use distinct contracts. A Platform API key or scope for one surface is not blanket access to all of them.