Account

Data structure

An Account resource provides the following fields:

  • href

    Link to the account resource itself.

  • openid

    Claimed user open id suffix.

  • preferredemail

    Preferred email address.

  • displayname

    Display name for the user.

  • status

    Status of the account. Possible values are:
    • ‘Not activated’
    • ‘Active’
    • ‘Deactivated (by user)’
    • ‘Suspended (by admin)’

  • verified

    True if the account is verified (atm, it checks if the user has a validated email address).

  • emails

    List of email addresses associated to the user, each one with an ‘href’ field linking to the corresponding email resource, and a boolean ‘verified’ field that indicates if the email has been verified or not.

    The list will have at the most 10 results, and they will be ordered from last created to oldest.

  • tokens

    List of oauth tokens associated to the user, each one with an ‘href’ field linking to the corresponding token resource, and a ‘name’ field that holds the name given to the token at creation time.

    The list will have at the most 10 results, and they will be ordered from last updated (last used) to less used.

Use cases

Create an account

POST /api/v2/accounts

Creates a new account

Form Parameters:
 
  • email – user’s email address
  • password – user’s password (min 8 chars)
  • displayname – user’s name
  • creation_source – a string describing source of user creation (optional)
  • captcha_id – (optional)
  • captcha_solution – (optional)
  • create_captcha – (optional, defaults to True)
Status Codes:

Errors

The errors are returned as a json-encoded dict with keys:

  • code: code name, see below for the list of names (e.g. ALREADY_REGISTERED)
  • message: error explanation (e.g. The email address is already registered)
  • extra: specific to each error (optional)

  • INVALID_DATA: The provided data is not valid or incomplete.

    Error status code 400.

    The extra attribute in the response will include all the fields that failed validation, like:

    {"code": "INVALID_DATA",
 "message": "Invalid request data",
 "extra": {"password": ["Field required"],
           "displayname": ["Field required"],
           "email": ["Field required"]}
}

  • ALREADY_REGISTERED: This email address is already registered.

    The error uses a 409 code, indicating a conflict.

    The extra field includes:

    • email: the email that was used to register

  • CAPTCHA_FAILURE: Failed response to captcha challenge.

    Error status code 403.

    This error has one field in the extra attribute.

    • capture_message: the error message returned by recaptcha.

  • CAPTCHA_REQUIRED: A captcha challenge is required to complete the request.

    Error status code 401.

    If create_captcha is True (the default), this error will include two fields in the extra attribute. If False, extra will be empty.

    • image_url: a link to an image containing the captcha challenge to be answered
    • captcha_id: the identifier for this specific challenge (which should be sent back along with the user provided response)

    The consumer should present the user with the image referred by the image_url attribute, and collect a response from the user.

    The consumer should then retry the request, including two extra parameters:

    • captcha_id (as provided in the error response)
    • captcha_solution: the user provided response to the captcha challenge

  • CAPTCHA_ERROR: The reCaptcha service is down or not working properly.

    Error status code 502.

    This error has the following fields.

    • recaptcha_reason text reason for the error
    • recaptcha_status_code * the http code returned by the recaptcha service
    • recaptcha_body * http body returned by the recaptcha service

    * These fields will be empty for non http network errors (like ‘connection refused’)

Examples

Request:

POST /api/v2/accounts HTTP/1.1
Host: login.ubuntu.com
Accept: application/json
Content-Type: application/json

{
  "email": "foo@example.com",
  "password": "thepassword",
  "displayname": "Foo Bar Baz"
}

If captcha is required

POST /api/v2/accounts HTTP/1.1
Host: login.ubuntu.com
Accept: application/json
Content-Type: application/json

{
  "email": "foo@example.com",
  "password": "thepassword",
  "displayname": "Foo Bar Baz",
  "captcha_id": "some-captcha-id",
  "captcha_solution": "the solution"
}

Response:

HTTP/1.1 201 CREATED
Vary: Accept
Content-Type: application/json
Location: /api/v2/accounts/openid123

{
  "href": "https://login.ubuntu.com/api/v2/accounts/openid123",
  "openid": "openid123",
  "preferredemail": "foo@example.com",
  "displayname": "Foo Bar Baz",
  "status": "NEW",
  "verified": false,
  "emails": [
    {
      "href": "https://login.ubuntu.com/api/v2/emails/foo@example.com"
    }
  ]
}

If captcha is required

HTTP/1.1 401 UNAUTHORIZED
Vary: Accept
Content-Type: application/json

{
  "code": "CAPTCHA_REQUIRED",
  "message": "Captcha validation required.",
  "extra": {
    "image_url": "https://www.google.com/recaptcha/image/foo.jpg",
    "captcha_id": "some-captcha-id"
  }
}