Users

The Mapped API also lets you interact with user information. If you're an admin, you have the ability to view, add, edit and delete users in your organization. As a non-admin user, someone with the EXPLORER role, you can edit some of your own details - like name and nickname - but for everyone else in your org, it's read-only.

Viewing Users

Viewing a list of your users is straightforward - just list out the various fields you want to see for each user. One common use would be the see the role(s) your users have assigned, which would look like the following:

Request Response
Copy
1
2
3
4
5
6
7
{
  users {
    id
    name
    roles
  }
}

If you wanted to search for a specific user, for example using the user's email, you can add a filter:

Request Response
Copy
1
2
3
4
5
6
7
{
  users(filter: {email: {eq: "[email protected]"}}) {
    id
    name
    email
  }
}

Inviting new, editing or deleting users, however, requires the use of a mutation, which is a bit more complicated.

Inviting Users

To add a new user, you would need to invite them to join your organization using the createInvite function. The potential new user would then receive an email with the invitation, which walks them through the remaining steps to register. After the call succeeds, the below code returns the details of the invitation for confirmation:

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
mutation {
	createInvite(
		input: {
			invite: {
				email: "[email protected]"
				roles: [EXPLORER]
				expiration: "2023-01-01T00:00:00"
			}
		}
	) {
		invite {
			id
			email
			status
			roles
			expiration
			created
		}
	}
}

In the above example, we're providing the new user's email, setting EXPLORER for roles - which is the standard user role (there's also ADMIN, which has all the elevated rights), and defining an expiration date (if you don't include an expiration, the default is 30 days).

Viewing Invites

If you want to view the invites that are still pending - i.e. haven't been accepted yet - you can make a call to invites:

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
{
  invites {
    id
    email
    roles
    created
    status
    expiration
  }
}

Updating Invites

If you meant to invite someone as an ADMIN, but set the invite as EXPLORER (or vice versa), you can update the invite as long as the user hasn't accepted it yet. The only fields you'll need are the invite id (which isn't editable, only used to identify the record to change) and roles.

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
mutation {
  updateInvite(input: {
		invite: {
			id: "INVITENFfU5MZTzESemWfdAXABCD",
			roles: [
				ADMIN
			]
		}
  }) {
    invite {
      id
	  roles
    }
  }
}

Deleting Invites

If you want to delete an invite that was sent out, all you'll need is the invite ID (retrievable when you run a call to invites as shown earlier):

Request Response
Copy
1
2
3
4
5
mutation {
	deleteInvite(input: { id: "INVITE7ZhkqFJ4pMWQXDvVjgpvAi" }) {
		_
	}
}

Editing Users

To edit an existing user's information, such as updating their name or nickname, you'll need to get their id first. The id field isn't editable, it's only used to identify the record you want to change. The Viewing Users example outlined earlier shows how to get the id for all users in the org.

In our following example, we're changing the nickname for the target user - note that you cannot edit a user's id, orgId or email - these are all set in stone when the user is created. If you want to change someone's email, they'll have to be removed and re-invited to the org. In addition, you cannot edit roles this way - head down to Adding or Removing User Roles for instructions on making those changes.

For the fields in the return object, we'll include id, email and nickname to ensure the value we changed did update, and for the right record:

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
mutation {
      updateUser(
        input: {
          user: {
            id: "1234abcd5678c3p0"
            nickname: "Ole One Hand"
          }
        }
      ) {
        user {
          id
          email
          nickname
        }
      }
    }

Adding or Changing User Role

If you want to add a role to a user, there's an independent field for that called assignRole. The userId argument is the same as the id in previous examples. Note that while this adds the role to the user, it does not "replace" the role that they already have; you'll need to follow up with a second request to remove the unwanted role (which is covered next):

Request Response
Copy
1
2
3
4
5
6
7
8
mutation {
  assignRole(input: {userId: "1234abcd5678c3p0", role: ADMIN}) {
    user {
      id
      roles
    }
  }
}

Removing User Role

To remove a role, you would make a call to removeRole and include the userId and role fields like so:

Request Response
Copy
1
2
3
4
5
6
7
8
mutation {
      removeRole(input: {userId: "1234abcd5678c3p0", role: EXPLORER}) {
        user {
          id
          roles
        }
      }
    }

Deleting Users

To delete a user entirely, you'll just need their id - you won't be able to delete using anything else. Since you really don't need anything back except a successful response code, we just include an underscore "field" for the response:

Request Response
Copy
1
2
3
4
5
mutation {
  deleteUser(input: { id: "1234abcd5678c3p0" }) {
    _
  }
}