About REST API

Authentication

Security scopes

Scopes ensure the token can only be used for what the add-on was authorised to do.

Your add-on declares the scopes required to be able to use REST API endpoints via its descriptor.

Learn more

To view the list of scopes and understand how to request scopes, read API scopes

Requesting an API access token

To make a call to the HipChat REST API for a tenant, your add-on must first programmatically request a temporary token.

There are four types of tokens:

Token typeMakes the REST call asExample scenario
Add-on tokenThe add-onYour add-on sends a notification message to a HipChat room for an event in your application.
User tokenA HipChat user

A user pastes a link to a file, with a URL that matches a webhook your add-on is listening to.

Your add-on then retrieves the content of the file, and post it as an attachment to a HipChat room on behalf of the user.

Personal access tokenYour HipChat user account

You want to test the REST API (this is the easiest way to generate a token).

Room notification token

The add-on (access limited to a room)

Your add-on is a notification-only add-on (see Guide for more details)

Learn more

To learn how to generate tokens, read API access tokens

Including the token in the request

The token can be used to make REST calls to HipChat, for example to send a notification message to a room.

You have the choice of providing your access token either as:

  • The 'auth_token' query parameter
1
2
GET /v2/room?auth_token=YOUR_TOKEN HTTP/1.1
  • The Authorization HTTP request header, which is more secure as you risk your access token showing up in server logs
1
2
GET /v2/room HTTP/1.1
Authorization: Bearer YOUR_TOKEN

Testing a token

To test if an auth token is valid and has access to a given method, include auth_test=true. The method's normal actions (messaging a room, listing users, etc) will not be performed. So, given the request:

1
2
GET /v2/room?auth_token=YOUR_TOKEN&auth_test=true HTTP/1.1
  • If the token is valid a HTTP 202 response will be returned.
  • If the token does not have access to the method, a standard HTTP 401 error will be returned.

Example: sending a notification message

To send a notification message, an add-on uses the HipChat REST API. HipChat currently supports plain text and HTML notifications. 

1
2
POST /v2/room/{id_or_name}/notification
Authorization: Bearer <token>
  
{
  "color": "green", 
  "message": "My notification message", 
  "notify": false, 
  "message_format": "text"
}

REST API endpoints

API reference

For a comprehensive documentation of the HipChat REST API, visit the API reference documentation.

Throughout the API documentation, you'll see a list of client types that may access a given resource operation. Each API access token has a logically associated client type, depending on how the token was generated. The possible client types are as follows:

Client typeDescription
Group client
  • An add-on that has been installed globally in a HipChat group is granted group client tokens
Room client
  • An add-on that has been installed in a HipChat room is granted room client tokens
  • A room notification token
User
  • A user token
  • A personal access token
OAuth clientAny of the above client types

Learn more

For a comprehensive documentation of the HipChat REST API, visit the API reference documentation.

API rate limits

Authentication tokens generated by add-ons are limited to a maximum number of calls executed in a particular time window. 

Learn more

To learn more about API rate limits, read API rate limits

API title expansion

In order to be minimise network traffic and help avoid API rate limits, the HipChat API provides title expansion. 

Learn more

To learn more about API title expansion, read API title expansion

Rate this page: