{"_id":"59c33dff9aea850010ac4304","project":"568bdc1483d2061900d86cdc","version":{"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","__v":19,"createdAt":"2017-08-30T20:39:44.453Z","releaseDate":"2017-08-30T20:39:44.453Z","categories":["59a7236e3fe4d90025117c10","59a72eb6cb0db3001b84cfe2","59a734eb757d030019b85af8","59c0243b1b2d07001a9d2b76","59c035e42126e10028effb12","59c06c40df5b3c0010584a13","59c1a5852cabe5002641a3e7","59c2fb00b2b45c0010b7a3d7","59c32ceb9aea850010ac4130","59c32e6e190c90003cb0d12f","59c33affb2b45c0010b7aa23","59c7dfa457bd8200105444dc","59c7e975c50cf30010d712a0","59cffdef0cd4dd0010294d54","59d0622ca91a810032c8f60c","59d06733c1aec60026253065","59d174d44ac471001a07b123","59d5a5e323e6e800103defb2","59ecf1d8ed507c001c52b255"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.0.0","version":"0"},"category":{"_id":"59c33affb2b45c0010b7aa23","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-09-21T04:07:27.858Z","from_sync":false,"order":15,"slug":"users-api","title":"Users API"},"user":"58cc41f21751ce2f003be3b7","__v":2,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T04:20:15.082Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"59a85b6b02c545000f08a77f","results":{"codes":[]},"examples":{"codes":[]},"method":"put","auth":"required","params":[{"_id":"59c33c119aea850010ac42b7","ref":"","in":"path","required":true,"desc":"","default":"","type":"string","name":"ecosystemId"},{"_id":"59c33c119aea850010ac42b6","ref":"","in":"path","required":true,"desc":"","default":"","type":"string","name":"userId"},{"_id":"59c33dff9aea850010ac430b","ref":"","in":"query","required":false,"desc":"","default":"","type":"string","name":"expiryType"},{"_id":"59c33dff9aea850010ac430a","ref":"","in":"query","required":false,"desc":"","default":"","type":"boolean","name":"generateToken"},{"_id":"59c33dff9aea850010ac4309","ref":"","in":"query","required":false,"desc":"","default":"","type":"int","name":"ttl"},{"_id":"59c33dff9aea850010ac4308","ref":"","in":"body","required":false,"desc":"","default":"","type":"string","name":"access"},{"_id":"59c33dff9aea850010ac4307","ref":"","in":"body","required":false,"desc":"","default":"","type":"string","name":"email"},{"_id":"59c33dff9aea850010ac4306","ref":"","in":"body","required":false,"desc":"","default":"","type":"object","name":"meta"},{"_id":"59c33dff9aea850010ac4305","ref":"","in":"header","required":false,"desc":"","default":"","type":"string","name":"x-system-metadata-prefix"}],"url":"/:ecosystemId;:userId"},"isReference":false,"order":1,"body":"# Details\n\nCreate or Update a user.\n\nThe user ID must be explicitly specified using the ecosystem ID which contains that user.\nAccess to an environment for a given user is provided by the “access” array. Each element in the array represents the access a user has to a specific environment. The access level can be either “Full” or “None.” Supply “Full” to create access, and “None” to remove access. Once access is removed, the array element which contains that access will also be deleted.\n\nThe token generation parameters should only be used if a new user is being created or if a significant update to the user is being made. Do not use this token specifically to generate a user token without creating or making changes to a user. Use endpoint `GET api/users/:id/tokens` when a new token should be generated without changing or creating a user.\n\nThe following token expiration types are valid:\n1. Infinite: A token that never expires.\n2. FixedTtl: A token that expires after a set amount of time (“fixed time to live”).\n3. SlidingTtl: A token that expires after a set amount of time from the last time it was used (“sliding time to live”). Using the token within the allotted time resets the amount of time it is valid.\n\nThis endpoint returns 201 when a user is created, and 200 when a user is updated.\n\nAn account token or server token may be used to run this endpoint.\n\n# Parameters\n\n## path\n\n- ecosystemId (required): The ID of the ecosystem.\n- id (required): The unique ID of a user.\n\n## query\n\n- expiryType (optional): The manner in which a generated user token should expire. Default is “FixedTtl.”\n- generateToken (optional): Whether a user token should be generated. Default is false.\n- ttl (optional): The time that a generated user token will be valid, in seconds. Default is 3600.\n\n## body\n\n- access (optional): The array of objects specifying a user's access to environments.\n- email (optional): The user's current valid email address.\n- meta (optional): The metadata associated with the user.\n\n## header\n\n- x-system-metadata-prefix (optional): A customized metadata prefix. The default is “$.”\n\n# Responses\n\n## 200\n\n- No content returned, only the status code. See the REST API “Standard Responses” page.\n\n## 201\n\n- No content returned, only the status code. See the REST API “Standard Responses” page.\n\n## 400\n\n- __Query Field Not Allowed:__ The standard error structure defines this error as invalid parameters, with additional parameters in the query string. In this context, it means that one or more query string fields are incorrect. They do not match the name(s) of the query string field(s) that are allowed for this endpoint.\n- __Ecosystem Invalid:__ The standard error structure defines this error as invalid parameters, with an invalid ID linked to the parameter that designates the ecosystem ID. In this context, it means that the ID given for an ecosystem was not valid.\n- __Token Duration Invalid:__ This error means that the token duration given was invalid, and the standard error structure lists this as invalid parameters. Token duration should be listed as a positive number of seconds.\n- __Token Expiration Type Invalid:__ This error means that the type of token expiration type given was invalid, and the standard error structure lists this as invalid parameters.\n- __Token Generation Invalid:__ This error means that the token generation flag given was invalid, and the standard error structure lists this as invalid parameters. The flag must be a boolean.\n- __Metadata Format Invalid:__ The standard error structure defines this error as invalid parameters. In this context, it means that metadata, when specified, should have been formatted as a valid JSON object, and it was not formatted that way.\n- __Environment Access Format Invalid:__ The standard error structure defines this error as invalid parameters. In this context, it means that the environment access object, when specified, should have been formatted as a valid JSON object, and it was not formatted that way.\n\n## 404\n\n- __Ecosystem Not Found:__ This error means that an ecosystem with the given ID was not found. This is distinct from an invalid ecosystem ID being specified; this means that the ecosystem ID once existed, but no longer does.\n\n# Examples\n\n## HTTP\n\n```\nPUT https://ioe.droplit.io/api/users/ECOSYSTEM-ID;USER-ID HTTP/1.1\nauthorization: TOKEN\ncontent-type: application/json\n{\n    \"access\": [\n        {\n            \"environmentId\": \"ENVIRONMENT-ID\",\n            \"accessLevel\": \"ACCESS-LEVEL\"\n        }\n    ],\n    \"email\": \"USER-EMAIL\",\n    \"meta\": {\n        \"$label\": \"Test user\"\n    }\n}\n```\n\n## HTTP (With Token)\n\n```\nPUT https://ioe.droplit.io/api/users/ECOSYSTEM-ID;USER-ID?generateToken=true&expiryType=FixedTtl&ttl=3600 HTTP/1.1\nauthorization: TOKEN\ncontent-type: application/json\n{\n    \"access\": [\n        {\n            \"environmentId\": \"ENVIRONMENT-ID\",\n            \"accessLevel\": \"ACCESS-LEVEL\"\n        }\n    ],\n    \"email\": \"USER-EMAIL\",\n    \"meta\": {\n        \"$label\": \"Test user\"\n    }\n}\n```\n\n## Droplit Console\n\n```\ncreate user: droplit user create USER-ID\ncreate user token: droplit user create-token USER-ID\nupdate user: droplit user update USER-ID PROPERTY-NAME PROPERTY-VALUE\n```","excerpt":"","slug":"users-create-update","type":"endpoint","title":"Create or Update a user."}

putCreate or Update a user.


Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

ecosystemId:
required
string
userId:
required
string

Query Params

expiryType:
string
generateToken:
boolean
ttl:
integer

Body Params

access:
string
email:
string
meta:
object

Headers

x-system-metadata-prefix:
string

Documentation

# Details Create or Update a user. The user ID must be explicitly specified using the ecosystem ID which contains that user. Access to an environment for a given user is provided by the “access” array. Each element in the array represents the access a user has to a specific environment. The access level can be either “Full” or “None.” Supply “Full” to create access, and “None” to remove access. Once access is removed, the array element which contains that access will also be deleted. The token generation parameters should only be used if a new user is being created or if a significant update to the user is being made. Do not use this token specifically to generate a user token without creating or making changes to a user. Use endpoint `GET api/users/:id/tokens` when a new token should be generated without changing or creating a user. The following token expiration types are valid: 1. Infinite: A token that never expires. 2. FixedTtl: A token that expires after a set amount of time (“fixed time to live”). 3. SlidingTtl: A token that expires after a set amount of time from the last time it was used (“sliding time to live”). Using the token within the allotted time resets the amount of time it is valid. This endpoint returns 201 when a user is created, and 200 when a user is updated. An account token or server token may be used to run this endpoint. # Parameters ## path - ecosystemId (required): The ID of the ecosystem. - id (required): The unique ID of a user. ## query - expiryType (optional): The manner in which a generated user token should expire. Default is “FixedTtl.” - generateToken (optional): Whether a user token should be generated. Default is false. - ttl (optional): The time that a generated user token will be valid, in seconds. Default is 3600. ## body - access (optional): The array of objects specifying a user's access to environments. - email (optional): The user's current valid email address. - meta (optional): The metadata associated with the user. ## header - x-system-metadata-prefix (optional): A customized metadata prefix. The default is “$.” # Responses ## 200 - No content returned, only the status code. See the REST API “Standard Responses” page. ## 201 - No content returned, only the status code. See the REST API “Standard Responses” page. ## 400 - __Query Field Not Allowed:__ The standard error structure defines this error as invalid parameters, with additional parameters in the query string. In this context, it means that one or more query string fields are incorrect. They do not match the name(s) of the query string field(s) that are allowed for this endpoint. - __Ecosystem Invalid:__ The standard error structure defines this error as invalid parameters, with an invalid ID linked to the parameter that designates the ecosystem ID. In this context, it means that the ID given for an ecosystem was not valid. - __Token Duration Invalid:__ This error means that the token duration given was invalid, and the standard error structure lists this as invalid parameters. Token duration should be listed as a positive number of seconds. - __Token Expiration Type Invalid:__ This error means that the type of token expiration type given was invalid, and the standard error structure lists this as invalid parameters. - __Token Generation Invalid:__ This error means that the token generation flag given was invalid, and the standard error structure lists this as invalid parameters. The flag must be a boolean. - __Metadata Format Invalid:__ The standard error structure defines this error as invalid parameters. In this context, it means that metadata, when specified, should have been formatted as a valid JSON object, and it was not formatted that way. - __Environment Access Format Invalid:__ The standard error structure defines this error as invalid parameters. In this context, it means that the environment access object, when specified, should have been formatted as a valid JSON object, and it was not formatted that way. ## 404 - __Ecosystem Not Found:__ This error means that an ecosystem with the given ID was not found. This is distinct from an invalid ecosystem ID being specified; this means that the ecosystem ID once existed, but no longer does. # Examples ## HTTP ``` PUT https://ioe.droplit.io/api/users/ECOSYSTEM-ID;USER-ID HTTP/1.1 authorization: TOKEN content-type: application/json { "access": [ { "environmentId": "ENVIRONMENT-ID", "accessLevel": "ACCESS-LEVEL" } ], "email": "USER-EMAIL", "meta": { "$label": "Test user" } } ``` ## HTTP (With Token) ``` PUT https://ioe.droplit.io/api/users/ECOSYSTEM-ID;USER-ID?generateToken=true&expiryType=FixedTtl&ttl=3600 HTTP/1.1 authorization: TOKEN content-type: application/json { "access": [ { "environmentId": "ENVIRONMENT-ID", "accessLevel": "ACCESS-LEVEL" } ], "email": "USER-EMAIL", "meta": { "$label": "Test user" } } ``` ## Droplit Console ``` create user: droplit user create USER-ID create user token: droplit user create-token USER-ID update user: droplit user update USER-ID PROPERTY-NAME PROPERTY-VALUE ```

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}