API access tokens

The following tokens are available:

Add-on generated tokens

Your add-on can use the OAuth ID and OAuth secret and capabilities document received via the Installation flow to obtain an access token, and call the HipChat REST API.

The key OAuth endpoints can be found in the capabilities document:

"capabilities": { 
	...,
	"oauth2Provider": {
    	"authorizationUrl": "https://www.hipchat.com/users/authorize",
    	"tokenUrl": "https://api.hipchat.com/v2/oauth/token"
	}
}
  • Token URL: used by the add-on to obtain an access token
  • Authorization URL: used by the add-on to obtain authorization from users to to act on their behalf

Add-on token

With an add-on token, your add-on can make a call to the HipChat REST API as the add-on (e.g. when the add-on "My add-on" sends a notification message, it will show as a message from "My add-on").

Your add-on can request a short lived token (valid for 1 hour) using the standard OAuth2 Client Credentials flow. 

To do that, construct a POST request to the token URL, using HTTP basic authentication (with the OAuth ID and secret as the basic username and password, respectively), containing the following form-encoded parameters:

POST /v2/oauth/token HTTP/1.1
Host: api.hipchat.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW  <-- Basic Auth using the oauth id and the oauth secret
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=send_notification+admin_room
  • grant_type - Must be client_credentials
  • scope - A space-delimited set of scopes the token should have access to. Note this list must be a subset of the scopes your integration requested in its capabilities descriptor.

If successful, the response will contain a token in a JSON-encoded body with the following fields:

  • access_token - Your new access token
  • token_type - Will always be bearer
  • scope - A space-delimited list of scopes this token is allowed to use
  • expires_in - The lifetime in seconds of the access token

The token will expire after one hour, after which your add-on needs to generate a new one using the same method. 

For more information, see the documentation for the token endpoint.

User token

With a user token, your add-on can make a call to the HipChat REST API, acting on behalf of a HipChat user.

To make a REST call to HipChat as a HipChat user, your add-on need to ask the user to grant you permission to act on his/her behalf.

Obtaining user approval

If an add-on wants to ask on behalf of users, it must declare it in its descriptor (OAuth2 consumer capability), and provide a redirection URL - which tells HipChat where to redirect the user once the user approved an add-on to act on their behalf:

"capabilities": {
	...,
	"oauth2Consumer": {
		redirectionUrls: [
			"https://example.com/oauth2/cb"
		]
	}
}

To obtain user approval, you need to follow the standard OAuth2 Authorization Grant flow:

   
Your add-on redirects the user to HipChat

Redirect the user to HipChat from your application, to the Authorization URL provided in the capabilities document:

https://www.hipchat.com/users/authorize?response_type=code
    &scope=view_group+send_notification
    &signup=0
    &client_id=<oauth id>
    &redirect_uri=https://example.com/oauth2/cb
    &state=<xsrf_token>
  • response_type: "code"
  • scope: list of scopes required. The scopes will be presented to the user, asking for confirmation. 
  • signup: 
    • if you specify "0", unauthenticated users will be sent to the HipChat sign-in page
    • if you specify "1", unauthenticated users will be sent to the HipChat sign-up page (which contains a sign-in link)
  • client_id: the OAuth client key that your add-on received on installation in a room or group.
  • redirect_uri: must match one of the redirectionUrls you've provided in the add-on descriptor
  • state: a random string generated by your application, which will be sent back to you as part of the redirect (to prevent cross-site request forgery)
The user approves the grant in HipChat HipChat then presents the user with an approval screen
HipChat redirects the user to your add-on

HipChat redirects the user to the provided redirect_uri, including the standard OAuth2 parameters and the HipChat group ID:

https://example.com/oauth2/cb?code=xyz&state=<xsrf_token>&group_id=1234
  • code: the authorization code
  • state: the XSRF token you provided. Check that it is the same as what you sent HipChat
  • group_id: the ID for the HipChat group the user belongs to
Your add-on can now request an API access token

The authorization code is a one time code that you can use to request an API access token.

Read the next section to understand how to request a token.

Requesting an API access token

To request a token, your add-on can use an OAuth2 Access Token Request.

To do that, construct a POST request to the token URL, using HTTP basic authentication (with the OAuth ID and secret as the basic username and password, respectively), containing the following form-encoded parameters:

POST /v2/oauth/token HTTP/1.1
Host: api.hipchat.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW  <-- Basic Auth using the oauth id and the oauth secret
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=xyz&redirect_uri=https%3A%2F%2Fexample%2Ecom%2Foauth2%2Fcb
  • grant_type must be 'authorization_code'
  • code: the authorization code received for the user
  • redirect_uri: must match the redirect_uri used in the OAuth2 Authorization Grant flow

The response should be similar to this:

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

As a response, you'll receive:

  • An access token will be valid for 1 hour, which you can use to call the HipChat REST API
  • A refresh token which you can use after the access token expires, to refresh it. 
Refreshing the token

To refresh the token, make a REST call to the same endpoint:

POST /v2/oauth/token HTTP/1.1
Host: api.hipchat.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW  <-- Basic Auth using the oauth id and the oauth secret
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=xyz
  • grant_type must be 'refresh_token'
  • refresh_token: the refresh token received previously

You will receive the same response, and can override the tokens received previously.

User generated tokens

Personal access tokens

You can generate a token for your own HipChat user account in the HipChat administration personal access token page.

This token does not expire, and has access to all the API's available to you, for all scopes.

You can for example use these tokens to test REST API calls when building an add-on.

Room notification tokens

Room owners are able to create a room notification token for a room. A room notification token can be used to send notification messages for a room, which is popular with light-weight, notification-only add-ons.


Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport