the standard login decorator to `@LoginRequired(api_access=True)`. 

After this change, a rhodecode view can be accessed without login by adding a 

GET parameter `?api_key=<api_key>` to url. By default this is only

enabled on RSS/ATOM feed views.

API ACCESS

++++++++++

All clients are required to send JSON-RPC spec JSON data::

    {   

        "id:<id>,

        "api_key":"<api_key>",

        "method":"<method_name>",

        "args":{"<arg_key>":"<arg_val>"}

    }

Example call for autopulling remotes repos using curl::

    curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'

Simply provide

 - *id* A value of any type, which is used to match the response with the request that it is replying to.

 - *api_key* for access and permission validation.

 - *method* is name of method to call

 - *args* is an key:value list of arguments to pass to method

.. note::

    api_key can be found in your user account page

RhodeCode API will return always a JSON-RPC response::

    {   

        "id":<id>,

        "result": "<result>",

        "error": null

    }

All responses from API will be `HTTP/1.0 200 OK`, if there's an error while

calling api *error* key from response will contain failure description

and result will be null.

API METHODS

+++++++++++

pull

----

Pulls given repo from remote location. Can be used to automatically keep

remote repos up to date. This command can be executed only using api_key

belonging to user with admin rights

INPUT::

    api_key : "<api_key>"

    method :  "pull"

    args :    {

                "repo_name" : "<reponame>"

              }

OUTPUT::

    result : "Pulled from <reponame>"

    error :  null

get_user

--------

Get's an user by username, Returns empty result if user is not found.

This command can be executed only using api_key belonging to user with admin 

rights.

INPUT::

    api_key : "<api_key>"

    method :  "get_user"

    args :    { 

                "username" : "<username>"

              }

OUTPUT::

    result: None if user does not exist or 

            {

                "id" :       "<id>",

                "username" : "<username>",

                "firstname": "<firstname>",

                "lastname" : "<lastname>",

                "email" :    "<email>",

                "active" :   "<bool>",

                "admin" :    "<bool>",

            }

    error:  null

get_users

---------

Lists all existing users. This command can be executed only using api_key

belonging to user with admin rights.

INPUT::

    api_key : "<api_key>"

    method :  "get_users"

    args :    { }

OUTPUT::

    result: [

              {

                "id" :       "<id>",

                "username" : "<username>",

                "firstname": "<firstname>",

                "lastname" : "<lastname>",

                "email" :    "<email>",

                "active" :   "<bool>",

                "admin" :    "<bool>",

              },

    	      …

            ]

    error:  null

create_user

-----------

Creates new user. This command can 

be executed only using api_key belonging to user with admin rights.

INPUT::

    api_key : "<api_key>"

    method :  "create_user"

    args :    {

                "username" :  "<username>",

                "password" :  "<password>",

                "email" :     "<useremail>",

                "firstname" : "<firstname> = None",

                "lastname" :  "<lastname> = None",

                "active" :    "<bool> = True",

                "admin" :     "<bool> = False",

                "ldap_dn" :   "<ldap_dn> = None"

              }

OUTPUT::

    result: {

              "id" : "<new_user_id>",

              "msg" : "created new user <username>"

            }

    error:  null

update_user

-----------

updates current one if such user exists. This command can 

be executed only using api_key belonging to user with admin rights.

INPUT::

    api_key : "<api_key>"

    method :  "update_user"

    args :    {

                "username" :  "<username>",

                "password" :  "<password>",

                "email" :     "<useremail>",

              }

OUTPUT::

    result: {

              "id" : "<edited_user_id>",

              "msg" : "updated user <username>"

            }

    error:  null

get_users_group

---------------

Gets an existing users group. This command can be executed only using api_key

belonging to user with admin rights.

INPUT::

    api_key : "<api_key>"

    method :  "get_users_group"

    args :    {

                "group_name" : "<name>"

              }

OUTPUT::

    result : None if group not exist

             {

               "id" :         "<id>",

               "group_name" : "<groupname>",

               "active":      "<bool>",

               "members" :  [

                              { "id" :       "<userid>",

                                "username" : "<username>",

                                "firstname": "<firstname>",

                                "lastname" : "<lastname>",

                                "email" :    "<email>",

                                "active" :   "<bool>",

                                "admin" :    "<bool>",

                                "ldap" :     "<ldap_dn>"

                              },

                              …

                            ]

             }

    error : null

get_users_groups

----------------

Lists all existing users groups. This command can be executed only using 

api_key belonging to user with admin rights.

INPUT::

    api_key : "<api_key>"

    method :  "get_users_groups"

    args :    { }

OUTPUT::

    result : [

               {

                 "id" :         "<id>",

                 "group_name" : "<groupname>",

                 "active":      "<bool>",

                 "members" :  [

	    	                    {

	    	                      "id" :       "<userid>",

	                              "username" : "<username>",

	                              "firstname": "<firstname>",

	                              "lastname" : "<lastname>",

	                              "email" :    "<email>",

	                              "active" :   "<bool>",

	                              "admin" :    "<bool>",

	                              "ldap" :     "<ldap_dn>"

	                            },

	    	                    …

	                          ]

	            }

              ]

    error : null

create_users_group

------------------

Creates new users group. This command can be executed only using api_key

belonging to user with admin rights

INPUT::

    :created_on: Aug 20, 2011

    :author: marcink

    :copyright: (C) 2011-2012 Marcin Kuzminski <marcin@python-works.com>

    :license: GPLv3, see COPYING for more details.

"""

# This program is free software; you can redistribute it and/or

# modify it under the terms of the GNU General Public License

# as published by the Free Software Foundation; version 2

# of the License or (at your opinion) any later version of the license.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program; if not, write to the Free Software

# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

# MA  02110-1301, USA.

import traceback

import logging

from rhodecode.controllers.api import JSONRPCController, JSONRPCError

from rhodecode.lib.auth import HasPermissionAllDecorator, \

    HasPermissionAnyDecorator, PasswordGenerator

from rhodecode.model.meta import Session

from rhodecode.model.scm import ScmModel

from rhodecode.model.db import User, UsersGroup, RepoGroup, Repository

from rhodecode.model.repo import RepoModel

from rhodecode.model.user import UserModel

from rhodecode.model.users_group import UsersGroupModel

from rhodecode.model.repos_group import ReposGroupModel

log = logging.getLogger(__name__)

class ApiController(JSONRPCController):

    """

    API Controller

    Each method needs to have USER as argument this is then based on given

    API_KEY propagated as instance of user object

    Preferably this should be first argument also

    Each function should also **raise** JSONRPCError for any

    errors that happens

    """

    @HasPermissionAllDecorator('hg.admin')

    def pull(self, apiuser, repo_name):

        """

        Dispatch pull action on given repo

        :param user:

        :param repo_name:

        """

        if Repository.is_valid(repo_name) is False:

            raise JSONRPCError('Unknown repo "%s"' % repo_name)

        try:

            ScmModel().pull_changes(repo_name, self.rhodecode_user.username)

            return 'Pulled from %s' % repo_name

        except Exception:

            raise JSONRPCError('Unable to pull changes from "%s"' % repo_name)

    @HasPermissionAllDecorator('hg.admin')

    def get_user(self, apiuser, username):

        """"

        Get a user by username

        :param apiuser:

        :param username:

        """

        user = User.get_by_username(username)

        if user is None:

            return user

        return dict(

            id=user.user_id,

            username=user.username,

            firstname=user.name,

            lastname=user.lastname,

            email=user.email,

            active=user.active,

            admin=user.admin,

        )

    @HasPermissionAllDecorator('hg.admin')

    def get_users(self, apiuser):

        """"

        Get all users

        :param apiuser:

        """

        result = []

        for user in User.getAll():

            result.append(

                dict(

                    id=user.user_id,

                    username=user.username,

                    firstname=user.name,

                    lastname=user.lastname,

                    email=user.email,

                    active=user.active,

                    admin=user.admin,

                )

            )

        return result

    @HasPermissionAllDecorator('hg.admin')

    def create_user(self, apiuser, username, email, password, firstname=None,

                    lastname=None, active=True, admin=False, ldap_dn=None):

        """

        Create new user

        :param apiuser:

        :param username:

        :param password:

        :param email:

        :param name:

        :param lastname:

        :param active:

        :param admin:

        :param ldap_dn:

        """

        if User.get_by_username(username):

            raise JSONRPCError("user %s already exist" % username)

        if User.get_by_email(email, case_insensitive=True):

            raise JSONRPCError("email %s already exist" % email)

        if ldap_dn:

            # generate temporary password if ldap_dn

            password = PasswordGenerator().gen_password(length=8)

        try:

            usr = UserModel().create_or_update(

                username, password, email, firstname,

                lastname, active, admin, ldap_dn

            )

            Session.commit()

            return dict(

                id=usr.user_id,

                msg='created new user %s' % username

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create user %s' % username)

    @HasPermissionAllDecorator('hg.admin')

        """

        Updates given user

        :param apiuser:

        :param username:

        :param password:

        :param email:

        :param name:

        :param lastname:

        :param active:

        :param admin:

        :param ldap_dn:

        """

            raise JSONRPCError("user %s does not exist" % username)

        try:

            usr = UserModel().create_or_update(

                username, password, email, firstname,

                lastname, active, admin, ldap_dn

            )

            Session.commit()

            return dict(

                id=usr.user_id,

                msg='updated user %s' % username

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to update user %s' % username)

    @HasPermissionAllDecorator('hg.admin')

    def get_users_group(self, apiuser, group_name):

        """"

        Get users group by name

        :param apiuser:

        :param group_name:

        """

        users_group = UsersGroup.get_by_group_name(group_name)

        if not users_group:

            return None

        members = []

        for user in users_group.members:

            user = user.user

            members.append(dict(id=user.user_id,

                            username=user.username,

                            firstname=user.name,

                            lastname=user.lastname,

                            email=user.email,

                            active=user.active,

                            admin=user.admin,

                            ldap=user.ldap_dn))

        return dict(id=users_group.users_group_id,

                    group_name=users_group.users_group_name,

                    active=users_group.users_group_active,

                    members=members)

    @HasPermissionAllDecorator('hg.admin')

    def get_users_groups(self, apiuser):

        """"

        Get all users groups

        :param apiuser:

        """

        result = []

        for users_group in UsersGroup.getAll():

            members = []

            for user in users_group.members:

                user = user.user

                members.append(dict(id=user.user_id,

                                username=user.username,

                                firstname=user.name,

                                lastname=user.lastname,

                                email=user.email,

                                active=user.active,

                                admin=user.admin,

                                ldap=user.ldap_dn))

            result.append(dict(id=users_group.users_group_id,

                                group_name=users_group.users_group_name,

                                active=users_group.users_group_active,

                                members=members))

        return result

    @HasPermissionAllDecorator('hg.admin')

    def create_users_group(self, apiuser, group_name, active=True):

        """

        Creates an new usergroup

        :param group_name:

        :param active:

        """

        if self.get_users_group(apiuser, group_name):

            raise JSONRPCError("users group %s already exist" % group_name)

        try:

            ug = UsersGroupModel().create(name=group_name, active=active)

            Session.commit()

            return dict(id=ug.users_group_id,

                        msg='created new users group %s' % group_name)

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create group %s' % group_name)

    @HasPermissionAllDecorator('hg.admin')

# -*- coding: utf-8 -*-

"""

    rhodecode.model.user

    ~~~~~~~~~~~~~~~~~~~~

    users model for RhodeCode

    :created_on: Apr 9, 2010

    :author: marcink

    :copyright: (C) 2010-2012 Marcin Kuzminski <marcin@python-works.com>

    :license: GPLv3, see COPYING for more details.

"""

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

import logging

import traceback

from pylons import url

from pylons.i18n.translation import _

from rhodecode.lib import safe_unicode

from rhodecode.lib.caching_query import FromCache

from rhodecode.model import BaseModel

from rhodecode.model.db import User, UserRepoToPerm, Repository, Permission, \

    UserToPerm, UsersGroupRepoToPerm, UsersGroupToPerm, UsersGroupMember, \

    Notification, RepoGroup, UserRepoGroupToPerm, UsersGroup

from rhodecode.lib.exceptions import DefaultUserException, \

    UserOwnsReposException

from sqlalchemy.exc import DatabaseError

from rhodecode.lib import generate_api_key

from sqlalchemy.orm import joinedload

log = logging.getLogger(__name__)

PERM_WEIGHTS = {

    'repository.none': 0,

    'repository.read': 1,

    'repository.write': 3,

    'repository.admin': 4,

    'group.none': 0,

    'group.read': 1,

    'group.write': 3,

    'group.admin': 4,

}

class UserModel(BaseModel):

    def __get_user(self, user):

        return self._get_instance(User, user, callback=User.get_by_username)

    def __get_perm(self, permission):

        return self._get_instance(Permission, permission,

                                  callback=Permission.get_by_key)

    def get(self, user_id, cache=False):

        user = self.sa.query(User)

        if cache:

            user = user.options(FromCache("sql_cache_short",

                                          "get_user_%s" % user_id))

        return user.get(user_id)

    def get_by_username(self, username, cache=False, case_insensitive=False):

        if case_insensitive:

            user = self.sa.query(User).filter(User.username.ilike(username))

        else:

            user = self.sa.query(User)\

                .filter(User.username == username)

        if cache:

            user = user.options(FromCache("sql_cache_short",

                                          "get_user_%s" % username))

        return user.scalar()

    def get_by_api_key(self, api_key, cache=False):

        return User.get_by_api_key(api_key, cache)

    def create(self, form_data):

        try:

            new_user = User()

            for k, v in form_data.items():

                setattr(new_user, k, v)

            new_user.api_key = generate_api_key(form_data['username'])

            self.sa.add(new_user)

            return new_user

        except:

            log.error(traceback.format_exc())

            raise

    def create_or_update(self, username, password, email, name, lastname,

                         active=True, admin=False, ldap_dn=None):

        """

        Creates a new instance if not found, or updates current one

        :param username:

        :param password:

        :param email:

        :param active:

        :param name:

        :param lastname:

        :param active:

        :param admin:

        :param ldap_dn:

        """

        from rhodecode.lib.auth import get_crypt_password

        log.debug('Checking for %s account in RhodeCode database' % username)

        user = User.get_by_username(username, case_insensitive=True)

        if user is None:

            log.debug('creating new user %s' % username)

            new_user = User()

        else:

            log.debug('updating user %s' % username)

            new_user = user

        try:

            new_user.username = username

            new_user.admin = admin

            new_user.password = get_crypt_password(password)

            new_user.api_key = generate_api_key(username)

            new_user.email = email

            new_user.active = active

            new_user.ldap_dn = safe_unicode(ldap_dn) if ldap_dn else None

            new_user.name = name

            new_user.lastname = lastname

            self.sa.add(new_user)

            return new_user

        except (DatabaseError,):

            log.error(traceback.format_exc())

            raise

    def create_for_container_auth(self, username, attrs):

        """

        Creates the given user if it's not already in the database

        :param username:

        :param attrs:

        """

        if self.get_by_username(username, case_insensitive=True) is None:

            # autogenerate email for container account without one

            generate_email = lambda usr: '%s@container_auth.account' % usr

            try:

                new_user = User()

                new_user.username = username

                new_user.password = None

                new_user.api_key = generate_api_key(username)

                new_user.email = attrs['email']

                new_user.active = attrs.get('active', True)

                new_user.name = attrs['name'] or generate_email(username)

                new_user.lastname = attrs['lastname']

                self.sa.add(new_user)

                return new_user

            except (DatabaseError,):