| CARVIEW |
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
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 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 2POST /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 beclient_credentialsscope- 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 tokentoken_type- Will always bebearerscope- A space-delimited list of scopes this token is allowed to useexpires_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
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:
1 2"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:
|
| 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:
|
| 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:
1 2POST /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 2POST /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.
Rate this page: