OAuth 2.0

OAuth 2.0 is an authorization framework that enables third-party applications to obtain access to Gitter on the user's behalf without getting their password.

All developers need to register their application before getting started. A registered OAuth 2.0 application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

Given the security implications of getting the implementation correct, we strongly encourage you to use available OAuth 2.0 libraries.

Demo App

There's a Node.JS demo app you can clone and play with at

Web Application Flow

Authorization Code Grant is probably the most used authorization flow. The flow is based on redirects and requires the client to have a web browser. Use this flow if your client is another web application.

1. Redirect users to request Gitter access


The following query string parameters can be used:

Name Description
client_id Required The registered client ID for your application.
response_type Required Use value code.
redirect_uri The URL in your app where users will be sent after authorization. See details below about redirect URLs.

2. Gitter redirects back to your site

If the user accepts your request, Gitter redirects back to your site with a temporary authorization code in the redirect URL as well as the state parameter provided in the previous step.

The redirect might look like


Exchange the code for an access token with


The following parameters should be present in the request:

Field Description
client_id Required The registered client ID for your application.
client_secret Required The client secret for your application.
code Required The authorization code returned from the initial request.
redirect_uri Required The URI registered with the application.
grant_type Required As defined in the OAuth 2.0 specification, this field must contain a value of authorization_code.

A successful response to this contains the following fields:

Field Description
access_token The token that can be used to access the Gitter API.
expires_in The remaining lifetime on the access token.
token_type The type of token received. At this time, this field will always have the value Bearer.

By default, the response will be represented as an application/x-www-form-urlencoded string, such as


However, you can also specify the JSON content type using the Accept header.

Accept: application/json
{"access_token":[omitted], "scope":"flow,private", "token_type":"bearer"}

Testing OAuth2 exchange using curl:

You can obtain a token using the command:

$ curl -X POST -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer {{token}}" "" -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","code":"CODE","grant_type":"authorization_code","redirect_uri":"YOUR_REDIRECT_URL"}'
Sorry, you can't post with this method (http)
  • curl
  • http

3. Make API requests with the access token.

The access token allows you to make requests to the API on behalf of a user.

Authorization: Bearer OAUTH-TOKEN

Check who you are authenticated as


  • none
GET /v1/user/me

Try it from the CLI:

$ curl -i -H "Accept: application/json" -H "Authorization: Bearer {{token}}" ""{{token}}
  • curl
  • http
  "id": "553d437215522ed4b3df8c50",
  "username": "MadLittleMods",
  "displayName": "Eric Eastwood",
  "url": "/MadLittleMods",
  "avatarUrl": "",
  "staff": true,
  "providers": [
  "v": 8,
  "gv": "3"