02.Authentication.md

Authentication

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 https://github.com/gitterHQ/gitter-demo-app

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

GET https://gitter.im/login/oauth/authorize

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

GET https://example.com/oauth/callback?code=deadbeef

Exchange the code for an access token with

POST https://gitter.im/login/oauth/token

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

access_token=[omitted]&scope=flow%2Cprivate&token_type=bearer

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:

'demo api-access';
{
  "verb": "post",
  "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages/:chatMessageId",
  "data": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "CODE",
    "grant_type": "authorization_code",
    "redirect_uri": "YOUR_REDIRECT_URL"
  }
}

3. Make API requests with the access token.

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

GET https://api.gitter.im/v1/user
Authorization: Bearer OAUTH-TOKEN
Host: api.gitter.im

Check who you are authenticated as

Parameters

• none

GET /v1/user/me

Try it from the CLI:

'demo api-access';
{
  "verb": "get",
  "resource": "{{api_url}}/v1/user/me"
}

{
  "id": "553d437215522ed4b3df8c50",
  "username": "MadLittleMods",
  "displayName": "Eric Eastwood",
  "url": "/MadLittleMods",
  "avatarUrl": "https://avatars-05.gitter.im/gh/uv/3/MadLittleMods",
  "staff": true,
  "providers": [
    "github"
  ],
  "v": 8,
  "gv": "3"
}