Scopes

The HipChat REST API endpoints are safeguarded by API scopes.

Your add-on must declare the scopes it requires based on which API endpoints it needs to use, via its descriptor. For example, an add-on with the following descriptor will be able to use the REST API endpoints to send notification messages to HipChat rooms, and create/archive/manage HipChat rooms:

1
2
"capabilities": {
    "hipchatApiConsumer": {
      "scopes": [
        "send_notification",
        "manage_rooms"
      ]
    }
}

When installing your add-on, users are presented with a dialog listing the scopes your add-on requested, and must accept these scopes before the installation continues.

Available scopes

Scope	Access
admin_group	Perform group administrative tasks
admin_room	Perform room administrative tasks
manage_rooms	Create, update, and remove rooms
send_message	Send private one-on-one messages
send_notification	Send room notifications
view_group	View users, rooms, and other group information
view_messages	View messages from chat rooms and private chats you have access to
view_room	View room information and participants, but not history