Lock or Unlock a Workspace

API Endpoint: lock_workspace

Locks and unlocks a workspace to restrict certain actions

Important

An API Key is required for ALL private workspace activities

The API Key name component can be added to your header using any of the following ways, “X-CKAN-API-Key”, “EDX-API-Key”, or “Authorization”.

Attention

Add the "User-Agent": parameter within the headers of the API request
Set "User-Agent": to the value "EDX-USER"

Workspace Lock Key Features

A workspace can be lock and unlocked within the EDX UI and via API script

Locking a Workspace

ONLY the following roles can lock a workspace

System Administrator
Workspace Administrator

Unlocking a Workspace

ONLY the following roles can unlock a workspace

System Administrator
Workspace Administrator who locked the workspace

Feature Functionaility in a Locked Workspace

When a user locks a workspace, functionality within the workspace is limited
The user who locks the workspace will have no restrictions of features within a workspace

Note

If the Lock Restriction field in the tables below are True, the feature is restricted when a workspace is locked

Parameters for Workspace Lock

Feature Name	Lock Restriction
`Delete Resource`	True
`Upload Resource`	True
`Edit Resource Metadata`	True
`Edit Resource License Type`	True
`Add Resource to Cart`	True
`View Resource`	False
`Download Resource`	False
`Rate Resource`	False
`Delete Resource from Recycle Bin`	True
`Recover Resource from Recycle Bin`	True
`Undo Last Action`	True
`Redo Last Action`	True
`Create Folder`	True
`Move Folder`	True
`Delete Folder`	True
`Rename Folder`	True

Feature Name	Lock Restriction
`Create Submission`	True
`View Submission`	False
`View JSON Metadata`	False
`Edit Submission`	True
`Add Resource`	True
`Follow`	False
`Push to Public`	True
`Apply for DOI and Push to Public`	True
`Edit Resources`	True
`Add Resource`	True
`Delete Resource`	True
`Change Resource License`	True
`Update Resource`	True

Feature Name	Lock Restriction
`Create Submission`	True
`Download Selected`	False
`Remove Selected`	False
`Clear Cart`	False
`View Resource`	False
`Rate Resource`	False
`Edit Resource`	True
`Add Resource`	True
`Edit Resource Metadata`	True
`Edit License Type`	True

Parameter Definitions

Parameter Name	Description	Required Fields
`workspace_id`	ID associated with the workspace	Required
`EDX-API-KEY`	API key associated with the the user	Required
`is_locked`	Boolean grabbed from database table to identify if workspace is locked	N/A
`notes`	String value that will show as a custom comment/note in the script output	Optional

Example 1: Lock and Unlock a Workspace

Attention

Add the "User-Agent": parameter within the headers of the API request
Set "User-Agent": to the value "EDX-USER"

Note

The is_locked output parameter’s value is gathered from the workspace lock database table

If is_locked value is True, the workspace is locked
If is_locked value is False, the workspace is unlocked

python
Workspace Lock Output
Workspace Unlock Output

import requests

headers = {
    "EDX-API-Key": 'YOUR_API_KEY_HERE',
    "User-Agent": 'EDX-USER',
    'Content-Type': 'application/json',
    'Accept':'application/json'
}

data = {
    'workspace_id': 'WORKSPACE-ID-HERE'
}

url = 'https://edx.netl.doe.gov/api/3/action/lock_workspace'
r = requests.post(
url,  # URL to API endpoint
headers=headers,  # Headers dictionary
json=data,  # Dictionary of data params

)
r_json = r.json()
print (r.json())

{'help': '/api/3/action/help_show?name=workspace_lock_api', 'success': True, 'result': {'is_locked': True}}

{'help': '/api/3/action/help_show?name=workspace_lock_api', 'success': True, 'result': {'is_locked': False}}

Example 2: Lock and Unlock a Workspace with a Custom Note/Comment

Attention

Add the "User-Agent": parameter within the headers of the API request
Set "User-Agent": to the value "EDX-USER"

Note

The is_locked output parameter’s value is gathered from the workspace lock database table

If is_locked value is True, the workspace is locked
If is_locked value is False, the workspace is unlocked

python
Workspace Lock Output with note
Workspace Lock Output without note

import requests

headers = {
    "EDX-API-Key": 'YOUR_API_KEY_HERE',
    "User-Agent": 'EDX-USER',
    'Content-Type': 'application/json',
    'Accept':'application/json'
}

data = {
    'workspace_id': 'WORKSPACE-ID-HERE',
    'notes': "NOTE MESSAGE HERE"  # custom note or message to add to the output of the script
}

url = 'https://edx.netl.doe.gov/api/3/action/lock_workspace'  # endpoint to perform the lock or unlock action
r = requests.post(
    url,  # URL to API endpoint
    headers=headers,  # Headers dictionary
    json=data,  # Dictionary of data params
)

url = 'https://edx.netl.doe.gov/api/3/action/check_workspace_lock'  # endpoint checking if workspace is locked
r2 = requests.post(
    url,  # URL to API endpoint
    headers=headers,  # Headers dictionary
    json=data,  # Dictionary of data params
)


print ("LOCK RESULT", r.json())
print ("CHECK RESULT", r2.json())

LOCK RESULT {'success': True, 'result': {'notes': 'NOTE-OUTPUT-HERE', 'is_locked': True}}
CHECK RESULT {'success': True, 'result': {'is_locked': True, 'locked_by': 'EDX Administrator (<user-email-here>)', 'date_locked': '2025-08-22 13:09', 'notes': 'NOTE-OUTPUT-HERE'}}

LOCK RESULT {'success': True, 'result': {'is_locked': True}}
CHECK RESULT {'success': True, 'result': {'is_locked': True, 'locked_by': 'EDX Administrator (<user-email-here>)', 'date_locked': '2025-08-22 13:13', 'notes': ''}}

Example: Error Message Output when Perfoming a Lock Restricted Action

Attention

Add the "User-Agent": parameter within the headers of the API request
Set "User-Agent": to the value "EDX-USER"

Note

The is_locked output parameter’s value is gathered from the workspace lock database table

If is_locked value is True, the workspace is locked
If is_locked value is False, the workspace is unlocked

python
Error Output

import requests
headers = {
   "EDX-API-Key": 'YOUR-API-KEY-HERE',
   "User-Agent": "EDX-USER"
}

data = {
   "workspace_id": 'YOUR-WORKSPACE-NAME-OR-ID-HERE',
   "folder_name": 'Test Folder 123',
   "parent_id": 'ID-OF-DESTINATION-FOLDER-HERE'
}

url = 'https://edx.netl.doe.gov/api/3/action/create_folder'

r = requests.post(
  url, # URL to API endpoint
  headers=headers, # Headers dictionary
  data=data, # Dictionary of data params
)

print (r.json())
print("End results")

{'help': '/api/3/action/help_show?name=resource_delete', 'error': {'message': 'This workspace was locked by <EDX-USERNAME-WHO-LOCKED-WORKSPACE> (<EDX-USER-EMAIL>)
and you cannot perform this action. It must be unlocked by the user who locked it.', '__type': 'Validation Error'}, 'success': False}