Skip to main content

Scenario Users

Users can be given access to either individual scenarios, or to saved scenarios and all their underlying scenarios. There are three different roles

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 registred 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. The response will contain a json of successfully processed users. When one of the users fails, the response will be 422 and contain the following:

  • success - The users that were successful.
  • errors - The users that were not successful.

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 reponse returns an Sending a POST request for a version tag:

Endpoint
POST /api/v3/scenarios/{scenario_id}/version
Path parameters
  • scenario_id number
    the scenario ID
Parameters
  • description string
    a short description of the tagged version
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",
      "roler": "scenario_collaborator"
    },
  ]

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

Update a users 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}/version
Path parameters
  • scenario_id number
    the scenario ID
Parameters
  • description string
    a short description of the tagged version
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",
      "roler": "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 DESTROY request for coupled users.

Endpoint
PUT /api/v3/scenarios/{scenario_id}/version
Path parameters
  • scenario_id number
    the scenario ID
Parameters
  • description string
    a short description of the tagged version
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",
    },
  ]

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