Create an oauth token¶

POST /api/v2/tokens/oauth¶

Creates a new OAuth token

Form Parameters:
	email – user’s email address password – user’s password token_name – a name for the token otp – one-time password (optional)
Status Codes:	200 OK – existing token returned 201 Created – token created 401 Unauthorized – invalid credentials or otp password required 403 Forbidden – invalid otp provided 403 Forbidden – account is suspended or inactive 403 Forbidden – email invalidated

A consumer requesting an authentication token must provide a token name. This name will be used by the user to identify the token when doing token management. The recommended scheme for token names is “application_name-device_name”.

This allows a user to easily identify which tokens belong to which application or to which device. For example they may wish to revoke all tokens for a particular application across their devices, or revoke all tokens on a particular device.

If a token name is requested that already exists (for this user) then the existing token will be returned (status code 200) instead of a new one being created (status code 201).

If an otp (one-time-password) is provided then it will checked against any two factor devices registered for the account. If the otp does not match any devices then a 403 will be returned.

If an otp is required for the account, but not sent, then a 401 will be returned.

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

{
  "email": "foo@example.com",
  "password": "thepassword",
  "token_name": "the-name"
}

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

{
  "email": "foo@example.com",
  "password": "thepassword",
  "token_name": "the-name",
  "otp": "123456"
}

HTTP/1.1 201 CREATED
Content-Type: application/json
Location: /api/v2/tokens/oauth/the-key

{
  "href": "https://login.ubuntu.com/api/v2/tokens/oauth/the-key",
  "token_key": "token-key",
  "token_secret": "token-secret",
  "token_name": "token-name",
  "consumer_key": "consumer-key",
  "consumer_secret": "consumer-secret"
  "date_created": "2013-01-11 12:43:23",
  "date_updated": "2013-01-11 12:43:23"
}

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

{
  "code": "INVALID_CREDENTIALS",
  "message": "Your email/password isn't correct.",
  "extra": {}
}

HTTP/1.1 401 UNAUTHORISED
Content-Type: application/json

{
  "code": "TWOFACTOR_REQUIRED",
  "message": "This account requires 2-factor authentication.",
  "extra": {}
}

Create a password reset token¶

POST /api/v2/tokens/password¶

Creates a new password reset token

Form Parameters:
	email – user’s email address
Status Codes:	201 Created – token created 403 Forbidden – account suspended 403 Forbidden – account deactivated 403 Forbidden – can not reset password 403 Forbidden – email invalidated 403 Forbidden – too many tokens

A consumer requesting a password reset token must provide an email address. This email address will be used to look up the user’s account in order to send the user an email containing a token that must be provided when setting the new password.

To prevent spamming unknowing users by sending multiple password reset emails, only a maximum amount of non-consumed tokens will be allowed to exist at any given time. When such limit is reached, attempting to create a new token will result in an error response.

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

{
  "email": "foo@example.com"
}

HTTP/1.1 201 CREATED
Content-Type: application/json
Location: /api/v2/tokens/password/the-key

{
  "email": "foo@example.com"
}

HTTP/1.1 403 FORBIDDEN
Content-Type: application/json

{
  "code": "TOO_MANY_TOKENS",
  "message": "Too many non-consumed tokens exist. Further token creation is not allowed until existing tokens are consumed.",
  "extra": {}
}