Workspace administration

A workspace is the scope for your flows, runs, integrations, credentials, and configuration. API fields use org_id for its identifier. A user can belong to several workspaces with a different role in each; a service API key belongs to one workspace.

On this page

Discover and create workspaces Manage members Review audit history Boundaries and related settings

Start with authentication, then confirm your selected workspace before changing membership or keys. Full request/response definitions are in the OpenAPI reference.

Discover and create workspaces

Operation	Purpose
`GET /me`	Current user, selected `org_id`, and session role.
`GET /users/me`	Adds workspace name and account metadata.
`GET /orgs`	Memberships with `org_id`, `org_name`, `role`, and `plan`.
`POST /orgs`	Creates a workspace and owner membership for the caller.

Create a workspace with an authenticated user session:

Shell

curl --fail-with-body -X POST "$DAGY_API_URL/orgs" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"org_name":"Commerce Engineering","plan":"free"}'

The response includes org_id, org_name, owner_email, plan, and timestamps. Save the identifier and select it explicitly with X-Org-Id on session requests. Use the free plan during onboarding; a plan field is not a payment or upgrade mechanism. Read actual account entitlements through usage and billing.

Verify the selection:

Shell

curl --fail-with-body "$DAGY_API_URL/me" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  -H "X-Org-Id: $DAGY_ORG_ID"

An invalid selection can fall back to another membership. Confirm the returned org_id matches your intent. API keys cannot use this header to move into another workspace. Scoped keys calling GET/POST workspace routes require the additional admin scope described in scope compatibility.

Manage members

Owners and admins hold admin.members. They can add a member to their selected workspace:

HTTP

POST /orgs/YOUR_ORG_ID/members

JSON

{"user_email":"engineer@example.com","role":"developer"}

Specify one of owner, admin, developer, or viewer explicitly. The current add-member endpoint has a legacy default role if omitted; use the explicit role to avoid unintended access. The email should match the member's sign-in email.

This operation adds membership directly. It does not send an invitation email or create an invitation-acceptance workflow. Tell the member which account and workspace to select using your normal team communication process.

Operation	Behavior
`GET /orgs/{org_id}/members`	Lists `user_email`, `org_id`, `role`, and `joined_at`; caller must select that workspace.
`PATCH /orgs/{org_id}/members/{email}/role`	Body `{"role":"viewer"}` changes an existing member's role; requires `admin.members`.
`GET /orgs/{org_id}/roles`	Current role-to-permission matrix.

URL-encode the email path segment. Unknown role values on the role-update endpoint return 422; missing members return 404. Attempting to manage another workspace returns 403.

There is currently no customer member-removal or workspace-deletion endpoint. For offboarding that requires removing membership, use the workspace's administrative/support process and revoke the person's application keys separately. Changing a user's role does not narrow already issued keys, which carry their own scopes.

Review audit history

Owners and admins can use admin.audit to inspect changes:

Shell

curl --fail-with-body --get "$DAGY_API_URL/audit-logs" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  --data-urlencode "resource_type=deployment" \
  --data-urlencode "action=promote" \
  --data-urlencode "limit=50"

Other filters are actor_email, start_date, and end_date. The response contains items, without a continuation cursor. Use date filters to narrow review windows.

Events include event_time, resource_type, resource_id, action, optional actor_email, change summaries in before_json/after_json, and metadata. The resource-specific route GET /audit-logs/resource/{resource_type}/{resource_id} is also available; prefer the workspace list with filters for a workspace audit export.

Audit recording is best effort for several operations. It is useful operational evidence, not a guarantee that every request or mutation appears. Redact sensitive data from exported events.

Workspace owner/admin roles manage workspace resources. Reserved platform administration, cross-workspace customer management, and support impersonation are not part of the customer integration API.

Use API keys for service access, environments for deployment configuration, and usage to monitor consumption. Keep production service keys under organizational ownership so they can be rotated when team membership changes.