1. Locations
  2. Manage Users

Locations

Manage Users

We have dedicated endpoints to help you manage which users should have access to which locations. Keep in mind that the owner and developer roles will always have access to all locations. Only admin and user roles can be scoped to specific locations.

Add and remove users to and from a location

POST
`/v1/locations/:location/users`

This endpoint enables management of user access to a specific location, supporting both individual and bulk user operations.

Request Parameters

URL Parameters

  • location_id (required): The unique identifier of the location, prefixed with loc_

Request Body

js 
        {
  "add": ["user_id1", "user_id2"],                              // Users to add to location
  "remove": ["user_id3", "user_id4"],                           // Users to remove from location
  "users": ["user_id1", "user_id2"] OR "users": "user_123",     // Alternative way to add users
  "overwrite": false                                            // Replace existing user list
}

The endpoint supports three modes of operation:

  1. Additive Mode (add/remove)
    • Specify users to add or remove while maintaining existing assignments.
    • Can be used simultaneously for adding and removing different users
  2. Bulk Assignment (users)
    • Provide a complete list of users to add.
    • Combines with existing user assignments.
  3. Replacement Mode (overwrite: true)
    • Replaces all existing user assignments with the new list

Some validations

The endpoint implements several validation measures:

  1. Organization Validation:
    • All specified users must belong to the location's organization.
    • Invalid user IDs return a 400 error with details.
  2. Protected Users:
    • Organization owners cannot be removed from locations.
    • Attempts to remove owners return a 401 error.
  3. Operation Validation:
    • Users cannot be in both add and remove lists.
    • Empty operations return a 400 error.
    • Duplicate user IDs are automatically removed.

Example Request

js 
        const data = {
  add: ["user_123", "user_456"],
  remove: ["user_789"],
  overwrite: false
};

const response = await fetch(`https://api.packagex.io/v1/locations/${location_id}/users`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

//We'll still respond with the location with the new users nested inside of it
const location = response.data;

Error Handling

The endpoint provides specific error responses for common issues:

  • Invalid Users
js 
        {
  "error": "2 users were not found in your organization",
  "code": "resource.not_found",
  "errors": ["invalid_user_id1", "invalid_user_id2"],
  "code": 400
}
  • Protected Users
js 
        {
  "error": "You cannot remove an owner from a location",
  "code": "user_ids",
  "errors": ["user_ids", "owner_user_id"],
  "status": 401
}

Add One User

This endpoint provides the ability for adding a single user to a location. While the bulk user management endpoint can handle all scenarios, this endpoint offers a more semantically appropriate method for single-user operations.

POST
`/v1/locations/:location/users/:user`
js 
        const data = {
  overwrite: false // Optional: When true, removes all other non-owner users
};

const response = await fetch(
  `https://api.packagex.io/v1/locations/${location_id}/users/${user_id}`,
  {
    method: "POST",
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(data),
  }
).then((res) => res.json());

//We'll still respond with the location with the new users nested inside of it
const location = response.data;

Delete Users

Delete Many Users

DELETE
`/v1/locations/:location/users`

You'll be able to delete many users at once by providing an array of user IDs in the request body.

js 
        const data = {
  users: ["2xFv1aJTgQTGGK6nWQeZ44P7hUR2", "hDfpP0P90gOuMgLOOCfdcvcyJiB3"],
};

const response = await fetch(`https://api.packagex.io/v1/locations/${location_id}/users`, {
  method: "DELETE",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

//We'll still respond with the location with the new users nested inside of it
const location = response.data;

Delete One User

DELETE
`/v1/locations/:location/users/:user`

You can delete a single user from a location using just the URL scheme with the location ID and user UD.

js 
        const response = await fetch(
  `https://api.packagex.io/v1/locations/${location_id}/users/${user_id}`,
  {
    method: "DELETE",
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    },
  }
).then((res) => res.json());

//We'll still respond with the location with the new users nested inside of it
const location = response.data;
Previous <- Delete Location
Next Layouts ->