Managing User Accounts and Permissions via CDA and CWMS-CLI

This guide is intended to help you manage user accounts and permissions in CWBI environments (DEV, TEST, PROD) via CDA and CWMS-CLI (version 0.4.0 or higher).

Step 1: Log In to the Target Environment

Before assigning roles, you must initialize your account in the target environment.

  1. Navigate to the CDA Swagger UI.
    1. e.g., https://water.dev.cwbi.us/cwms-data/swagger-ui
  2. Click Sign In
  4. It may take you back to the home screen. Got back to the Swagger UI and you should see now see Reauthenticate/Sign out 
  5.  

Step 2: Authenticate Your Session

Now you should authenticate your session by running a test endpoint.

  1. Under the Authorization section, expand the Get auth keys option and click Try it out.
  2. You should expect to see a 403 "Missing roles {Role{name='CWMS Users'}}" error.
    1. If you receive a token error, repeat the authorization step (Step 1 above).
  3. Provide your user ID to a CWMS ADMIN so they can complete Step 3.

Step 3: Manage Roles using CWMS-CLI or CDA UI

Administrative users with CWMS ADMIN privileges can manage user roles using CWMS-CLI (version 0.4.0 or greater) or through a web UI application in CDA.

CCD UI


follow the steps outlined in the following documentation

https://cwms-data-api.readthedocs.io/latest/user-onboarding.html

***As of 10/16/2026 the ONBORD USERS option is only in Dev.  If you do not see it use the ASSIGN OFFICE button for new users.  You should be able to search for the user or you might have to enter the entire user ID to find them.  Then select the office you are adding permissions for***

In Dev

In Test/Prod


CWMS-CLI

Finding Users

#list all users in the database
cwms-cli users user-ids -a $CDA_ROOT -k $API_KEY

#list all users with permissions for a specific office
cwms-cli users user-ids -a $CDA_ROOT -k $API_KEY -o MVP

#search for users matching a text pattern (in this example any user with wilson in anyplace in the user ID will be shown)
cwms-cli users user-ids -a $CDA_ROOT -k $API_KEY -ul wilson

Viewing Roles

#view all roles assigned to a user across all offices
cwms-cli users roles list-user -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.2345455

#view roles assigned to a user for a specific office
cwms-cli users roles list-user -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.2345455 -o SWL

Assigning Roles

Roles can be assigned individually or by using shorthand keywords (readonly, readwrite, admin) to apply standard role bundles automatically.

#show all available roles
cwms-cli users roles list-all -a $CDA_URL -k $CDA_API_KEY

#assign readwrite permissions to a user for office SWL
cwms-cli users roles add -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.2345455 --roles readwrite -o SWL

#assign specific roles to a user for office SWT
cwms-cli users roles add -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.2345455 --roles "CWMS Users,All Users" -o SWT

Removing Roles


#remove all roles for a user for a specific office (Note: 'All Users' cannot be deleted)
cwms-cli users roles delete -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.1102680282 --roles all -o SWL

#delete specific roles from a user for a specific office
cwms-cli users roles delete -a $CDA_URL -k $CDA_API_KEY -u WILSON.DAVID.L.1102680282 --roles "CWMS USER" -o SWT

Step 4: Create an API Key (Optional)

This step is only required for automated scripts or CDA functions that use an API key. You must have active user permissions before generating a key.

  1. Authorize your session on the target environment's Swagger page following the steps outlined in Step 1 above.
  2. Locate your exact user ID (typically formatted as LASTNAME.FIRSTNAME.MIDDLE.EDIPI, viewable via the user profile endpoint).
  3. Go to the POST auth/keys endpoint and click Try it out.
  4. Submit the JSON body containing your key name and expiration date by clicking Execute.
  5.  Copy and securely save the generated API key from the response.