Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Onezone REST API Oneprovider REST API Onepanel REST API

Create new user

POST /users

Creates a new user.

The fullName and username may be provided directly or derived from linked accounts.

Full name resolution:

  1. The value of the fullName parameter, if provided
  2. The first valid fullName from the linked accounts (after normalization)
  3. Unnamed User, if none of the above

NOTE: the value Unnamed User is treated as a missing value (i.e. equivalent to unspecified fullName).

Username resolution:

  1. The value of the username parameter, if provided
  2. The first valid username from the linked accounts (after normalization)
  3. null (no username), if none of the above

This operation requires oz_users_create admin privilege.

Example cURL requests

Create a new user

curl -u username:password -H "Content-type: application/json" \
-X POST -d '{ "username" : "new_user", "password": "lS1c6FD2mxB2ff" }' \
https://$ZONE_HOST/api/v3/onezone/users

Create a new user with a preconfigured linked account

curl -u username:password -H "Content-type: application/json" \
-X POST -d '{ 
  "linkedAccounts": [{
    "idp" : "egi",
    "username" : "janedoe",
    "subjectId" : "96ac30df1113de761bb42967da314dffe725d7b9@egi.eu",
    "groups" : [
      "urn:mace:egi.eu:group:test-group.egi.eu:role=vm_operator#aai.egi.eu",
      "urn:mace:egi.eu:group:test-group.egi.eu:role=member#aai.egi.eu"
    ],
    "fullName" : "Jane Done",
    "entitlements" : [
      "urn:mace:egi.eu:group:test-group.egi.eu:role=vm_operator#aai.egi.eu",
      "urn:mace:egi.eu:group:test-group.egi.eu:role=member#aai.egi.eu"
    ],
    "emails" : [
      "janedoe@example.com"
    ],
    "custom" : {
      "role": "developer"
    }
  }]
}' \
https://$ZONE_HOST/api/v3/onezone/users

Request body

application/json

User name.

PropertyType & Description
fullName
string

User's full name (given names + surname). Defaults to Unnamed User.

username
string

User's human-readable identifier, unique across the system. Makes it easier to identify the user and can be used for signing in with password. Defaults to null (no username).

password
string

User's password (in plaintext). Typically used for admin accounts and users that cannot log in using an Identity Provider.

linkedAccounts
array of objects (LinkedAccount)

The list of preconfigured linked accounts. May be useful to create a user account before they log in. Requires knowledge of at least the user's subject ID in the IdP.

idp required
string

Id of the Identity Provider, as specified in Onezone's auth.config.

subjectId required
string

Unique user Id assigned by the Identity Provider.

fullName
string

User's full name (given names + surname).

username
string

User's human-readable identifier, unique across the system. Makes it easier to identify the user and can be used for signing in with password.

emails
array of strings

The list of user email accounts.

entitlements
array of strings

A list of strings denoting user group memberships as acquired from the identity provider. Memberships are in Onedata normalized form.

custom
object

Custom user data collected upon login, depending on Onezone auth.config.

Request Examples

application/json 
{
  "fullName": "Rudolf Lingens",
  "username": "r.lingens",
  "password": "lS1c6FD2mxB2ff"
}

Responses

application/json
201

URI of the created user in the form https://$ZONE_HOST/api/onezone/v3/users/{id} is returned in the response Location header.

400

Invalid request.

PropertyType & Description
error
object

Object describing an error.

id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

Example

application/json
{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}
401

Authentication error.

PropertyType & Description
error
object

Object describing an error.

id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

Example

application/json
{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}
403

Authorization error.

PropertyType & Description
error
object

Object describing an error.

id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

Example

application/json
{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}
404

Resource not found.

PropertyType & Description
error
object

Object describing an error.

id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

Example

application/json
{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}
500

Internal server Error.

PropertyType & Description
error
object

Object describing an error.

id required
string

String identifying the error type. Does not change between error instances.

description required
string

Human readable error description. May contain information specific to given error instance.

details
object

Details about the error instance. The object schema is specific to each error type.

Example

application/json
{
  "error": {
    "id": "badValueString",
    "details": {
      "key": "name"
    },
    "description": "Bad value: provided \"name\" must be a string."
  }
}