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:

1
2
"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

Your add-on can request a short lived token (valid for 8 hours) 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:

1
2
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 8 hours, 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

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:

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

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

1
2
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>

1
2
https://example.com/oauth2/cb?code=xyz&state=<
xsrf_token>&group_id=1234

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:

1
2
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:

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

As a response, you'll receive:

• An access token will be valid for 8 hours, 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:

1
2
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.