HipChat REST API
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.
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 type||Makes the REST call as||Example scenario|
|Add-on token||The add-on||Your add-on sends a notification message to a HipChat room for an event in your application.|
|User token||A 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 token||Your 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)|
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
AuthorizationHTTP request header, which is more secure as you risk your access token showing up in server logs
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:
- 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.
REST API endpoints
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:
|OAuth client||Any of the above client types|
API rate limits
Authentication tokens generated by add-ons are limited to a maximum number of calls executed in a particular time window.
API title expansion
In order to be minimise network traffic and help avoid API rate limits, the HipChat API provides title expansion.