Skip to main content

Scenario Users

Users can be given access to either individual scenarios, or to saved scenarios and all their underlying scenarios. This endpoint manages users on regular scenarios. For managing users on saved scenarios, see Managing saved scenario users. To understand the difference between scenarios and saved scenarios, see Scenarios vs Saved Scenarios.

The user object​

The user object consist of the following two fields:

  • name - The username of the user, when the user is registered to the energy transition model. OR
  • email - If the user is not yet registered to the energy transition model.
  • role - The role the user has within the scenario.

There are three different types of roles, a detailed description can be found here.

  • scenario_owner - An owner of the scenario, can add other users and has all rights (read/write/destroy).
  • scenario_collaborator - A collaborator to the scenario, has rights to read and update the scenario.
  • scenario_viewer - A user that can view the contents of the scenario, even if it is marked as private.

Batch requests​

All user actions can be done in batches: adding or changing multiple users in one request. Each user is processed independently. The response will contain a JSON array of successfully processed users. When one or more users fail, the response will be 422 and contain the following:

  • success - The users that were successfully processed.
  • errors - The users that were not successful, with error details.
Partial success persistence

When a bulk operation returns partial success, the successful changes are persisted to the database. Only the failed operations need to be retried.

Get the users for a scenario​

Only a scenario owner can access this information. Sending a GET request for the users coupled to a scenario:

Endpoint
GET /api/v3/scenarios/{scenario_id}/users
Path parameters
  • scenario_id number
    the scenario ID
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:delete

    Delete your public and private scenarios

Example request
GET /api/v3/scenarios/0/users HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN
Example response

[
  {
    "user_id": 1,
    "name": "David",
    "role": "scenario_collaborator"
  },
  {
    "user_id": 20,
    "name": "Emma",
    "role": "scenario_owner"
  }
],

Add a user to a scenario​

It is possible to add multiple users to the scenario at once. When one of the creations fails, the response returns a 422 with success and errors.

Endpoint
POST /api/v3/scenarios/{scenario_id}/users
Path parameters
  • scenario_id number
    the scenario ID
Parameters
  • scenario_users array
    array of user objects to add
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:delete

    Delete your public and private scenarios

Example request
POST /api/v3/scenarios/0/users HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN

{
  "scenario_users": [
    {
      "user_email": "john@our_company.com",
      "role": "scenario_collaborator"
    },
  ]

}
Example response
[
  {
    "user_id": 2,
    "name": "John",
    "role": "scenario_collaborator"
  },
],

Update a user's role​

To change their role the user has to be identified by either: their user_id, their coupling id id, or their email user_email. Sending a PUT request for coupled users.

Endpoint
PUT /api/v3/scenarios/{scenario_id}/users
Path parameters
  • scenario_id number
    the scenario ID
Parameters
  • scenario_users array
    array of user objects to update
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:delete

    Delete your public and private scenarios

Example request
PUT /api/v3/scenarios/0/users HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN

{
  "scenario_users": [
    {
      "user_email": "john@our_company.com",
      "role": "scenario_viewer"
    },
  ]

}
Example response
[
  {
    "user_id": 2,
    "name": "John",
    "role": "scenario_viewer"
  },
],

Remove a user from a scenario​

To remove a user, the user has to be identified by either: their user_id, their coupling id id, or their email user_email. Sending a DELETE request for coupled users.

Endpoint
DELETE /api/v3/scenarios/{scenario_id}/users
Path parameters
  • scenario_id number
    the scenario ID
Parameters
  • scenario_users array
    array of user objects to remove
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:delete

    Delete your public and private scenarios

Example request
DELETE /api/v3/scenarios/0/users HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN

{
  "scenario_users": [
    {
      "user_email": "john@our_company.com",
    },
  ]

}
Example response
[
  {
    "user_id": 2,
    "name": "John",
    "role": "scenario_viewer"
  },
],

Remove all users from a scenario​

Remove all users except owners from a scenario in a single request.

Endpoint
DELETE /api/v3/scenarios/{scenario_id}/users/destroy_all
Path parameters
  • scenario_id number
    the scenario ID
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:delete

    Delete your public and private scenarios

Example request
DELETE /api/v3/scenarios/0/users/destroy_all HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN
Example response
{
  "message": "All users except owners have been removed"
}