Workspace API: Getting Started

Use the Workspace API for supported project and workspace user automation.

Before you start

1. Ask Diggle to enable Workspace API for your workspace and provide its exact workspaceId. Include your workspace name in the request; the name itself is not the ID.
2. As a workspace admin, create a key under Manage Workspace → Integrations. See Workspace API Authentication.
3. Keep the key in server-side secret storage. Run the example from a trusted terminal or backend.

Your first request

Replace both placeholders before running this read request. For production automation, inject the key from your secret store.

curl --request POST 'https://api.diggle.com/procedure/getWorkspaceUsers' \
  --header 'Authorization: Bearer <workspace-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{"body":{"workspaceId":"<workspace-id>"}}'

A successful request returns HTTP 200 and a JSON array. Example showing selected fields:

[
  {
    "user_id": "<user-id>",
    "name": "Example Trainer",
    "email": "[email protected]",
    "workspace_role": "creator",
    "status": "registered"
  }
]

An empty result is []. Keep the returned user_id for operations that require the canonical Diggle user ID.

Requests

Send HTTPS POST requests to https://api.diggle.com/procedure/{procedureName} with Content-Type: application/json and a Workspace API Bearer key.

Request envelope

{
  "body": {
    "workspaceId": "<workspace-id>"
  }
}

Place procedure parameters inside body.

Responses

Successful calls normally return HTTP 200. The response is the procedure result directly: a JSON string identifier, an object, an array, or null. deleteProject returns no result body. There is no common data wrapper.

Workspace scope

Create the key in the workspace you intend to manage. Workspace identifiers and project identifiers must refer to that workspace. Workspace API keys are separate from SCIM provisioning tokens and SSO credentials; they are not global Diggle account credentials.

Identifiers

Retries and idempotency

upsertWorkspaceUser reconciles a user by workspace and normalized email. Repeating revokeWorkspaceUserAccess returns the same revoked result if the relationship is already absent. createProject creates a new identifier on every successful call; do not automatically retry an ambiguous create. No caller-supplied idempotency key is documented.

Errors

Workspace API errors are plain text, not SCIM Error objects. Status handling varies by procedure; API & SCIM Errors describes the error formats. Do not interpret every 500 as a transient failure.

Common workflows

Create or update a user

1. Call upsertWorkspaceUser with the workspace ID and an approved email. Supply only the fields you intend to change.
2. Retain the returned user ID. The optional projects array replaces explicit project grants; omit it to retain them.
3. Verify the result with getWorkspaceUsers or getWorkspaceUser.

Revoke workspace access

1. Resolve the canonical user_id through the Workspace API.
2. Call revokeWorkspaceUserAccess with workspaceId and userId.
3. Verify that access to the selected workspace is removed. The global account remains. Another qualifying Enterprise workspace preserves Enterprise access; otherwise an ordinary user becomes Free. Cancelled personal paid access is not restored.

Rotate a key

As a workspace admin, select Rotate API key under Manage Workspace → Integrations, confirm, copy the replacement once and update your integration immediately. Verify it with the read request above. The replaced key stops working immediately.

Recover a locally revoked SCIM user

1. An authorized admin clears only the local block using the separate clearLocalBlock action.
2. The designated SCIM source sends active=true.
3. Verify workspace access and reassign required private project access in Diggle. Unblocking alone does not restore access.

Related articles

• Workspace API Authentication
• Workspace API Procedures
• API & SCIM Errors