https://docs.energytransitionmodel.com/assets/js/63b7fc37.b78ec3f8.js

1"use strict";(self.webpackChunktech_docs=self.webpackChunktech_docs||[]).push([[956],{2020(e,s,n){n.r(s),n.d(s,{assets:()=>h,contentTitle:()=>d,default:()=>m,frontMatter:()=>l,metadata:()=>r,toc:()=>u});const r=JSON.parse('{"id":"api/users","title":"Scenario Users","description":"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.","source":"@site/docs/api/users.md","sourceDirName":"api","slug":"/api/users","permalink":"/api/users","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{"id":"users","title":"Scenario Users","sidebar_label":"Scenario Users"},"sidebar":"apiSidebar","previous":{"title":"Scenario Version Tags","permalink":"/api/version-tag"},"next":{"title":"Scenario Interpolation","permalink":"/api/interpolation"}}');var a=n(4848),i=n(8453);const o={name:"scenario_id",type:"number",description:"the scenario ID"},t={index:{endpoint:"/api/v3/scenarios/{scenario_id}/users",method:"GET",path_parameters:[o],token:{scopes:["scenarios:delete"]}},create:{endpoint:"/api/v3/scenarios/{scenario_id}/users",method:"POST",path_parameters:[o],parameters:[{name:"scenario_users",type:"array",description:"array of user objects to add"}],token:{scopes:["scenarios:delete"]}},update:{endpoint:"/api/v3/scenarios/{scenario_id}/users",method:"PUT",path_parameters:[o],parameters:[{name:"scenario_users",type:"array",description:"array of user objects to update"}],token:{scopes:["scenarios:delete"]}},destroy:{endpoint:"/api/v3/scenarios/{scenario_id}/users",method:"DELETE",path_parameters:[o],parameters:[{name:"scenario_users",type:"array",description:"array of user objects to remove"}],token:{scopes:["scenarios:delete"]}},destroyAll:{endpoint:"/api/v3/scenarios/{scenario_id}/users/destroy_all",method:"DELETE",path_parameters:[o],token:{scopes:["scenarios:delete"]}}};var c=n(4140);const l={id:"users",title:"Scenario Users",sidebar_label:"Scenario Users"},d=void 0,h={},u=[{value:"The user object",id:"the-user-object",level:2},{value:"Batch requests",id:"batch-requests",level:2},{value:"Get the users for a scenario",id:"get-the-users-for-a-scenario",level:2},{value:"Add a user to a scenario",id:"add-a-user-to-a-scenario",level:2},{value:"Update a user's role",id:"update-a-users-role",level:2},{value:"Remove a user from a scenario",id:"remove-a-user-from-a-scenario",level:2},{value:"Remove all users from a scenario",id:"remove-all-users-from-a-scenario",level:2}];function p(e){const s={a:"a",admonition:"admonition",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsxs)(s.p,{children:["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 ",(0,a.jsx)(s.a,{href:"/api/saved-scenarios#managing-saved-scenario-users",children:"Managing saved scenario users"}),". To understand the difference between scenarios and saved scenarios, see ",(0,a.jsx)(s.a,{href:"/api/saved-scenarios#scenarios-vs-saved-scenarios",children:"Scenarios vs Saved Scenarios"}),"."]}),"\n",(0,a.jsx)(s.h2,{id:"the-user-object",children:"The user object"}),"\n",(0,a.jsx)(s.p,{children:"The user object consist of the following two fields:"}),"\n",(0,a.jsxs)(s.ul,{children:["\n",(0,a.jsxs)(s.li,{children:[(0,a.jsx)(s.code,{children:"name"})," - The username of the user, when the user is registered to the energy transition model. OR"]}),"\n",(0,a.jsxs)(s.li,{children:[(0,a.jsx)(s.code,{children:"email"})," - If the user is not yet registered to the energy transition model."]}),"\n",(0,a.jsxs)(s.li,{children:[(0,a.jsx)(s.code,{children:"role"})," - The role the user has within the scenario."]}),"\n"]}),"\n",(0,a.jsxs)(s.p,{children:["There are three different types of roles, a detailed description can be found ",(0,a.jsx)(s.a,{href:"/main/user_manual/managing-scenarios/scenario-manage-access",children:"here"}),"."]}),"\n",(0,a.jsxs)(s.ul,{children:["\n",(0,a.jsxs)(s.li,{children:[(0,a.jsx)(s.code,{children:"scenario_owner"})," - An owner of the scenario, can add other users and has all rights (read/write/destroy)."]}),"\n",(0,a.jsxs)(s.li,{children:[(0,a.jsx)(s.code,{children:"scenario_collaborator"})," - A collaborator to the scenario, has rights to read and update the scenario."]}),"\n",(0,a.jsxs)(s.li,{children:[(0,a.jsx)(s.code,{children:"scenario_viewer"})," - A user that can view the contents of the scenario, even if it is marked as private."]}),"\n"]}),"\n",(0,a.jsx)(s.h2,{id:"batch-requests",children:"Batch requests"}),"\n",(0,a.jsxs)(s.p,{children:["All user actions can be done in batches: adding or changing multiple users in one request. Each user is processed independently. The response will c

1ontain a JSON array of successfully processed users. When one or more users fail, the response will be ",(0,a.jsx)(s.code,{children:"422"})," and contain the following:"]}),"\n",(0,a.jsxs)(s.ul,{children:["\n",(0,a.jsxs)(s.li,{children:[(0,a.jsx)(s.code,{children:"success"})," - The users that were successfully processed."]}),"\n",(0,a.jsxs)(s.li,{children:[(0,a.jsx)(s.code,{children:"errors"})," - The users that were not successful, with error details."]}),"\n"]}),"\n",(0,a.jsx)(s.admonition,{title:"Partial success persistence",type:"info",children:(0,a.jsxs)(s.p,{children:["When a bulk operation returns partial success, the successful changes ",(0,a.jsx)(s.strong,{children:"are persisted"})," to the database. Only the failed operations need to be retried."]})}),"\n",(0,a.jsx)(s.h2,{id:"get-the-users-for-a-scenario",children:"Get the users for a scenario"}),"\n",(0,a.jsx)(s.p,{children:"Only a scenario owner can access this information.\nSending a GET request for the users coupled to a scenario:"}),"\n",(0,a.jsx)(c.A,{data:t.index}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-http",metastring:'title="Example request"',children:"GET /api/v3/scenarios/0/users HTTP/2\nHost: engine.energytransitionmodel.com\nAccept: application/json\nAuthorization: Bearer YOUR_TOKEN\n"})}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-json",metastring:'title="Example response"',children:'\n[\n  {\n    "user_id": 1,\n    "name": "David",\n    "role": "scenario_collaborator"\n  },\n  {\n    "user_id": 20,\n    "name": "Emma",\n    "role": "scenario_owner"\n  }\n],\n\n'})}),"\n",(0,a.jsx)(s.h2,{id:"add-a-user-to-a-scenario",children:"Add a user to a scenario"}),"\n",(0,a.jsxs)(s.p,{children:["It is possible to add multiple users to the scenario at once.\nWhen one of the creations fails, the response returns a ",(0,a.jsx)(s.code,{children:"422"})," with success and errors."]}),"\n",(0,a.jsx)(c.A,{data:t.create}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-http",metastring:'title="Example request"',children:'POST /api/v3/scenarios/0/users HTTP/2\nHost: engine.energytransitionmodel.com\nAccept: application/json\nAuthorization: Bearer YOUR_TOKEN\n\n{\n  "scenario_users": [\n    {\n      "user_email": "john@our_company.com",\n      "role": "scenario_collaborator"\n    },\n  ]\n\n}\n'})}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-json",metastring:'title="Example response"',children:'[\n  {\n    "user_id": 2,\n    "name": "John",\n    "role": "scenario_collaborator"\n  },\n],\n'})}),"\n",(0,a.jsx)(s.h2,{id:"update-a-users-role",children:"Update a user's role"}),"\n",(0,a.jsxs)(s.p,{children:["To change their role the user has to be identified by either: their ",(0,a.jsx)(s.code,{children:"user_id"}),", their coupling id ",(0,a.jsx)(s.code,{children:"id"}),", or their email ",(0,a.jsx)(s.code,{children:"user_email"}),".\nSending a PUT request for coupled users."]}),"\n",(0,a.jsx)(c.A,{data:t.update}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-http",metastring:'title="Example request"',children:'PUT /api/v3/scenarios/0/users HTTP/2\nHost: engine.energytransitionmodel.com\nAccept: application/json\nAuthorization: Bearer YOUR_TOKEN\n\n{\n  "scenario_users": [\n    {\n      "user_email": "john@our_company.com",\n      "role": "scenario_viewer"\n    },\n  ]\n\n}\n'})}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-json",metastring:'title="Example response"',children:'[\n  {\n    "user_id": 2,\n    "name": "John",\n    "role": "scenario_viewer"\n  },\n],\n'})}),"\n",(0,a.jsx)(s.h2,{id:"remove-a-user-from-a-scenario",children:"Remove a user from a scenario"}),"\n",(0,a.jsxs)(s.p,{children:["To remove a user, the user has to be identified by either: their ",(0,a.jsx)(s.code,{children:"user_id"}),", their coupling id ",(0,a.jsx)(s.code,{children:"id"}),", or their email ",(0,a.jsx)(s.code,{children:"user_email"}),".\nSending a DELETE request for coupled users."]}),"\n",(0,a.jsx)(c.A,{data:t.destroy}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-http",metastring:'title="Example request"',children:'DELETE /api/v3/scenarios/0/users HTTP/2\nHost: engine.energytransitionmodel.com\nAccept: application/json\nAuthorization: Bearer YOUR_TOKEN\n\n{\n  "scenario_users": [\n    {\n      "user_email": "john@our_

1company.com",\n    },\n  ]\n\n}\n'})}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-json",metastring:'title="Example response"',children:'[\n  {\n    "user_id": 2,\n    "name": "John",\n    "role": "scenario_viewer"\n  },\n],\n'})}),"\n",(0,a.jsx)(s.h2,{id:"remove-all-users-from-a-scenario",children:"Remove all users from a scenario"}),"\n",(0,a.jsx)(s.p,{children:"Remove all users except owners from a scenario in a single request."}),"\n",(0,a.jsx)(c.A,{data:t.destroyAll}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-http",metastring:'title="Example request"',children:"DELETE /api/v3/scenarios/0/users/destroy_all HTTP/2\nHost: engine.energytransitionmodel.com\nAccept: application/json\nAuthorization: Bearer YOUR_TOKEN\n"})}),"\n",(0,a.jsx)(s.pre,{children:(0,a.jsx)(s.code,{className:"language-json",metastring:'title="Example response"',children:'{\n  "message": "All users except owners have been removed"\n}\n'})})]})}function m(e={}){const{wrapper:s}={...(0,i.R)(),...e.components};return s?(0,a.jsx)(s,{...e,children:(0,a.jsx)(p,{...e})}):p(e)}},4140(e,s,n){n.d(s,{A:()=>j});n(6540);var r=n(8774);const a="apiEndpoint_M4PY",i="endpoint_aTO5",o="paramDescription_Pb5j",t="requiredParam_Qfv_",c="type_sBG3";var l=n(4848);const d=e=>{if(!e||!e.length)return null;const s=e.map(e=>(0,l.jsxs)("li",{children:[(0,l.jsxs)("div",{children:[(0,l.jsx)("code",{children:e.name})," ",(0,l.jsx)("code",{className:c,children:e.type}),e.required?(0,l.jsx)("span",{className:t,children:"Required"}):null]}),(0,l.jsx)("div",{className:o,dangerouslySetInnerHTML:{__html:e.description}})]},e.name));return(0,l.jsx)("ul",{children:s})},h={"scenarios:read":"Read your public and private scenarios","scenarios:write":"Create and update your public and private scenarios","scenarios:delete":"Delete your public and private scenarios"},u=e=>{let{scopes:s,type:n="required"}=e;return s&&s.length?(console.log(n),(0,l.jsxs)(l.Fragment,{children:[(0,l.jsx)("dt",{children:"Token"}),(0,l.jsxs)("dd",{children:[(0,l.jsx)("p",{style:{marginTop:"0.125rem",marginBottom:"0.5rem",fontWeight:400,fontSize:"0.875rem"},children:(0,l.jsx)(p,{type:n})}),(0,l.jsx)("ul",{children:s.map(e=>(0,l.jsx)(m,{scope:e},e))})]})]})):null},p=e=>{let{type:s}=e;return"optional"===s?(0,l.jsxs)(l.Fragment,{children:["An ",(0,l.jsx)(r.A,{to:"/api/authentication",children:"authentication token"})," is optional for this endpoint, but required to access private data."]}):"optional-owned"===s?(0,l.jsxs)(l.Fragment,{children:["An ",(0,l.jsx)(r.A,{to:"/api/authentication",children:"authentication token"})," is optional for this endpoint when accessing"," ",(0,l.jsx)(r.A,{to:"/api/authentication#using-the-api-without-authentication",children:"unowned data"})," but required when accessing data owned by the user."]}):(0,l.jsxs)(l.Fragment,{children:["This endpoint requires an ",(0,l.jsx)(r.A,{to:"/api/authentication",children:"authentication token"})," with at least the following scopes:"]})},m=e=>{let{scope:s}=e;return(0,l.jsx)(l.Fragment,{children:(0,l.jsxs)("li",{children:[(0,l.jsx)("code",{children:s}),(0,l.jsx)("p",{style:{marginTop:0,marginBottom:0,fontSize:"0.875rem"},children:h[s]})]})})},j=e=>{let{data:s}=e;const n=d(s.path_parameters),r=d(s.parameters);return(0,l.jsxs)("dl",{className:a,children:[(0,l.jsx)("dt",{children:"Endpoint"}),(0,l.jsxs)("dd",{className:i,children:[s.method," ",s.endpoint]}),n?(0,l.jsx)("dt",{children:"Path parameters"}):null,n?(0,l.jsx)("dd",{children:n}):null,r?(0,l.jsx)("dt",{children:"Parameters"}):null,r?(0,l.jsx)("dd",{children:r}):null,(0,l.jsx)(u,Object.assign({},s.token))]})}},8453(e,s,n){n.d(s,{R:()=>o,x:()=>t});var r=n(6540);const a={},i=r.createContext(a);function o(e){const s=r.useContext(i);return r.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function t(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:o(e.components),r.createElement(i.Provider,{value:s},e.children)}}}]);