<commit_before># Client Endpoints

## Retrieve All Clients
Retrieves all valid OAuth clients. This requires either the `admin` scope, or `role:admin` with an admin user.

```
GET /v2/clients
```

**Example Request:**
```sh
curl -X GET \
  -H "Authorization: ${ACCESS_TOKEN}" \
  https://northstar.dosomething.org/v2/clients
```

**Example Response:**
```js
// 200 OK

{
  "data": [
    {
      "client_id": "trusted-test-client",
      "client_secret": "<KEY>",
      "scope": [
        "admin",
        "user",
        "role:admin"
      ],
      "refresh_tokens": 28,
      "updated_at": "2016-07-07T15:46:21+0000",
      "created_at": "2016-07-06T18:26:04+0000"
    },
    {
      "client_id": "untrusted-test-client",
      "client_secret": "<KEY>",
      "scope": [
        "user"
      ],
      "refresh_tokens": 16,
      "updated_at": "2016-07-06T18:26:04+0000",
      "created_at": "2016-07-06T18:26:04+0000"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}
```

## Create a Client
Creates a new OAuth client. This requires either the `admin` scope, or `role:admin` with an admin user.

```
POST /v2/clients
```

**Parameters:**

```js
{
  /* Application name registering for the new key */
  client_id: String

  /* Whitelisted client scope(s) */
  scope: Array
}
```

**Example Request:**
```sh
curl -X POST \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"client_id": "test application", "scope": ["user"]}' \
  https://northstar.dosomething.org/v2/clients
```


**Example Responses:**
```js
// 200 OK

{
  "data": {
    "client_id": "test-application",
    "client_secret": "<KEY>",
    "scope": [
      "user"
    ],
    "refresh_tokens": 0,
    "updated_at": "2015-05-19 17:10:37",
    "created_at": "2015-05-19 17:10:37",
  }
}
```

## Retrieve a Client
View details for an OAuth client. This requires either the `admin` scope, or `role:admin` with an admin user.

```
GET /v2/clients/:client_id
```

**Example Request:**
```sh
curl -X GET\
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  https://northstar.dosomething.org/v2/clients/test-application
```


**Example Responses:**
```js
// 200 OK

{
  "data": {
    "client_id": "testapplication",
    "client_secret": "<KEY>",
    "scope": [
      "admin",
      "user"
    ],
    "refresh_tokens": 32,
    "updated_at": "2015-05-19 17:10:37",
    "created_at": "2015-05-19 17:10:37",
  }
}
```

## Update a Client
Updates an existing OAuth client's ID or scope(s). This requires either the `admin` scope, or `role:admin` with an admin user.

```
PUT /v2/clients/:client_id
```

**Parameters:**

```js
{
  /* (optional) Change the whitelisted scope(s) for this application. */
  scope: Array
}
```

**Example Request:**
```sh
curl -X PUT \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"scope": ["admin", "user"]}' \
  https://northstar.dosomething.org/v2/clients/test-application
```


**Example Responses:**
```js
// 200 OK

{
  "data": {
    "client_id": "testapplication",
    "client_secret": "<KEY>",
    "scope": [
      "admin",
      "user"
    ],
    "refresh_tokens": 32,<commit_msg>Add documentation for new OAuth title & description fields.<commit_after># Client Endpoints

## Retrieve All Clients
Retrieves all valid OAuth clients. This requires either the `admin` scope, or `role:admin` with an admin user.

```
GET /v2/clients
```

**Example Request:**
```sh
curl -X GET \
  -H "Authorization: ${ACCESS_TOKEN}" \
  https://northstar.dosomething.org/v2/clients
```

**Example Response:**
```js
// 200 OK

{
  "data": [
    {
      "title": "Trusted Test Client",
      "description": "A trusted example client.",
      "client_id": "trusted-test-client",
      "client_secret": "<KEY>",
      "scope": [
        "admin",
        "user",
        "role:admin"
      ],
      "refresh_tokens": 28,
      "updated_at": "2016-07-07T15:46:21+0000",
      "created_at": "2016-07-06T18:26:04+0000"
    },
    {
      "title": "Untrusted Test Client",
      "description": "A untrusted example client.",
      "client_id": "untrusted-test-client",
      "client_secret": "<KEY>",
      "scope": [
        "user"
      ],
      "refresh_tokens": 16,
      "updated_at": "2016-07-06T18:26:04+0000",
      "created_at": "2016-07-06T18:26:04+0000"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}
```

## Create a Client
Creates a new OAuth client. This requires either the `admin` scope, or `role:admin` with an admin user.

```
POST /v2/clients
```

**Parameters:**

```js
{
  /* The application's title. */
  title: String

  /* (optional) The description for this application. */
  description: String
  
  /* Application ID for the new key */
  client_id: String

  /* Whitelisted client scope(s) */
  scope: Array
}
```

**Example Request:**
```sh
curl -X POST \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"title": "Test Application", "description: "An example app.", "client_id": "test-application", "scope": ["user"]}' \
  https://northstar.dosomething.org/v2/clients
```


**Example Responses:**
```js
// 200 OK

{
  "data": {
    "title": "Test Application",
    "description": "An example app.",
    "client_id": "test-application",
    "client_secret": "<KEY>",
    "scope": [
      "user"
    ],
    "refresh_tokens": 0,
    "updated_at": "2015-05-19 17:10:37",
    "created_at": "2015-05-19 17:10:37",
  }
}
```

## Retrieve a Client
View details for an OAuth client. This requires either the `admin` scope, or `role:admin` with an admin user.

```
GET /v2/clients/:client_id
```

**Example Request:**
```sh
curl -X GET\
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  https://northstar.dosomething.org/v2/clients/test-application
```


**Example Responses:**
```js
// 200 OK

{
  "data": {
    "title": "Test Application",
    "description": "An example app.",
    "client_id": "testapplication",
    "client_secret": "<KEY>",
    "scope": [
      "admin",
      "user"
    ],
    "refresh_tokens": 32,
    "updated_at": "2015-05-19 17:10:37",
    "created_at": "2015-05-19 17:10:37",
  }
}
```

## Update a Client
Updates an existing OAuth client's ID or scope(s). This requires either the `admin` scope, or `role:admin` with an admin user.

```
PUT /v2/clients/:client_id
```

**Parameters:**

```js
{
  /* (optional) Change this application's title. */
  title: String

  /* (optional) Change the description for this application. */
  description: String

  /* (optional) Change the whitelisted scope(s) for this application. */
  scope: Array
}
```

**Example Request:**
```sh
curl -X PUT \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"scope": ["admin", "user"]}' \
  https://northstar.dosomething.org/v2/clients/test-application
```


**Example Responses:**
```js
// 200 OK

{
  "data": {
    "title": "Test Application",
    "description": "An example app.",
    "client_id": "testapplication",
    "client_secret": "<KEY>",
    "scope": [
      "admin",
      "user"
    ],
    "refresh_tokens": 32,
{'fraction_non_alphanumeric': 0.1904385618332675, 'fraction_numerical': 0.04293428157513499, 'mean_word_length': 2.959332638164755, 'pattern_counts': {'":': 97, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7371666', 'n_tokens_mistral': 2986, 'n_tokens_neox': 2681, 'n_words': 663}