Create and manage users

Overview

This tutorial describes the process to create and manage users. It shows how to browse and create users, add them to a team, set their roles, and replace keys. Check out the Accounts & users guide for more details.

🚧

Only Platform Administrators and Account Administrators can create and manage users.

Navigate the account

The steps in this section are optional. They validate the account where the user needs to be created and that the user doesn’t already exist.

Send a request to retrieve accounts to see a list of accounts:

HTTP

GET /api/accounting/accounts HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: trial.app.modzy.com

Send a request to get account details with the account identifier to see details such as account status, existing users, and users status:

HTTP

GET /api/accounting/accounts/demo_account_id HTTP/1.1
Authorization: ApiKey apikey.modzy
Accept: application/json
Content-Type: application/json
Host: trial.app.modzy.com

Send a request to search users with an email to validate the user doesn’t already exist:

HTTP

POST /api/accounting/users/search HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ApiKey apikey.modzy
Host: trial.app.modzy.com

JSON

{
  "identifiers":[
   "[email protected]"
  ]
}

Create a user

Create a user with the account id, user’s name, last name, and email:

HTTP

POST /api/accounting/accounts/demo_account_id/users HTTP/1.1
Authorization: ApiKey apikey.modzy
Accept: application/json
Content-Type: application/json
Host: trial.app.modzy.com

JSON

{
  "firstName": "User",
  "lastName": "Demo",
  "email": "[email protected]",
  "title": "just a user",
  "externalIdentifier": "[email protected]"
}

📘

Optionally, add the user’s title, external identifier, and source.

👍

Modzy returns the API key’s prefix required to assign roles. Store this information to use it later in the process.

Add the user to a team

Users added to a team get a team key with status active and receive an invitation email with a link to access the team.

Add the user to the team:

HTTP

POST /api/accounting/teams/demo-team-identifier/members HTTP/1.1
Authorization: ApiKey apikey.modzy
Accept: application/json
Content-Type: application/json
Host: trial.app.modzy.com

JSON

[
  {
    "identifier": "demo-team-user"
  }
]

Create a user and a new team related

Besides the default user creation, it is possible to create a user and a new team related to it. The team contains only one person (the created user) and it gets a team key with status active.

HTTP

POST /api/accounting/accounts/demo_account_id/users HTTP/1.1
Authorization: ApiKey apikey.modzy
Accept: application/json
Content-Type: application/json
Host: trial.app.modzy.com

JSON

{
  "firstName": "User",
  "lastName": "Demo",
  "email": "[email protected]",
  "title": "just a user",
  "externalIdentifier": "[email protected]",
  "team"{
  		"name": "New team name",
     	"adminUserIdentifier": "adminUserId",
    	"accessKeyRoles": [
      		"role 1",
         	"role 2"
       ] 
  }
    
}

The team can be an empty JSON object (without children parameters: "team": {}). In that case:

• The team name is: "Team" + firstName + " " + lastName.
• The team admin is the new user itself.
• The access key contains ACCOUNT_ADMIN and TEAM_ROLE roles. If the request provides a list, Modzy validates it and appends the roles to the team key.

Set the team key's roles

Different roles have different authorization levels across the APIs. Check out the Authorization guide for more details.

List existing roles to navigate the different options:

HTTP

GET /api/accounting/roles HTTP/1.1
Accept: application/json
Host: trial.app.modzy.com

Update the API key’s roles with the key’s prefix and the list of roles:

HTTP

PUT /api/accounting/access-keys/apikey_prefix/roles HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ApiKey apikey.modzy
Host: trial.app.modzy.com

JSON

[
  {
    "identifier" : "DEVELOPER"
  }
]

📘

Each user has a single team key for each team. However, they may have multiple project keys.