# Authentication

## OAuth 2.0

[OAuth 2.0](http://tools.ietf.org/html/rfc6749) 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](https://developer.gitter.im/apps) 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](https://github.com/gitterHQ/gitter-demo-app)

### Web Application Flow

[Authorization Code Grant](http://tools.ietf.org/html/rfc6749#section-4.1) 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"
}
```