<commit_before># Firefox Accounts OAuth Server API

## Overview

### URL Structure

```
https://<server-url>/v1/<api-endpoint>
```

Note that:

- All API access must be over HTTPS
- The URL embeds a version identifier "v1"; future revisions of this API may introduce new version numbers.
- The base URL of the server may be configured on a per-client basis

### Errors

Invalid requests will return 4XX responses. Internal failures will return 5XX. Both will include JSON responses describing the error.

Example error:

```js
{
  "code": 400, // matches the HTTP status code
  "errno": 101, // stable application-level error number
  "error": "Bad Request", // string description of error type
  "message": "Unknown client"
}
```

The currently-defined error responses are:

- status code, errno: description
- 400, 101: unknown client id
- 400, 102: incorrect client secret
- 400, 103: redirect_uri doesn't match registered value
- 400, 104: invalid fxa assertion 
- 400, 105: unknown code
- 400, 106: incorrect code
- 400, 107: expired code
- 400, 108: invalid token
- 400, 109: invalid request parameter
- 500, 999: internal server error

## API Endpoints


- [GET /v1/authorization][redirect]
- [POST /v1/authorization][authorization]
- [POST /v1/token][token]
- [GET /v1/client/:id][client]
- [POST /v1/verify][verify]

### GET /v1/client/:id

This endpoint is for the fxa-content-server to retreive information
about a client to show in its user interface.

#### Request Parameters

- `id`: The `client_id` of a client asking for permission.

Example:

```
https://oauth.accounts.firefox.com/v1/client/5901bd09376fadaa076afacef5251b6a
```

#### Response

A valid 200 response will be a JSON blob with the following properties:

- `name`: A string name of the client.
- `image_uri`: A url to a logo or image that represents the client.
- `redirect_uri`: The url registered to redirect to after successful oauth.

Example:

```js
{
  "name": "Where's My Fox",
  "image_uri": "https://mozilla.org/firefox.png",
  "redirect_uri": "https://wheres.my.firefox.com/oauth"
}
```

### GET /v1/authorization

This endpoint starts the OAuth flow. A client redirects the user agent
to this url. This endpoint will then redirect to the appropriate
content-server page.

### POST /v1/authorization

This endpoint should be used by the fxa-content-server, requesting that
we supply a short-lived code (currently 15 minutes) that will be sent
back to the client. This code will be traded for a token at the
[token][] endpoint.

#### Request Parameters

- `client_id`: The id returned from client registration.
- `assertion`: A FxA assertion for the signed-in user.
- `state`: A value that will be returned to the client as-is upon redirection, so that clients can verify the redirect is authentic.
- `redirect_uri`: Optional. If supplied, a string URL of where to redirect afterwards. Must match URL from registration.
- `scope`: Optional. A string-separated list of scopes that the user has authorized. This could be pruned by the user at the confirmation dialog.

#### Response

A valid request will return a 200 response, with JSON containing the `redirect` to follow. It will include the following query parameters:

- `code`: A string that the client will trade with the [token][] endpoint. Codes have a configurable expiration value, default is 15 minutes.
- `state`: The same value as was passed as a request parameter.

Example:

```js
{
  "redirect": "https://example.domain/path?foo=bar&code=asdfqwerty&state=zxcvasdf"
}
```

### POST /v1/token

After having received a [code][], the client sends that code (most
likely a server-side request) to this endpoint, to receive a
longer-lived token that can be used to access attached services for a
particular user.

#### Request Parameters

- `client_id`: The id returned from client registration.
- `client_secret`: The secret returned from client registration.
- `code`: A string that was received from the [authorization][] endpoint.

#### Response

A valid request will return a JSON response with these properties:

- `access_token`: A string that can be used for authorized requests to service providers.
- `scope`: A string of space-separated permissions that this token has. May differ from requested scopes, since user can deny permissions.
- `token_type`: A string representing the token type. Currently will always be "bearer".

Example:

```js
{
  "access_token": "5<PASSWORD>",
  "scopes": [],
  "token_type": "bearer"
}
```

### POST /v1/verify

Attached services can post tokens to this endpoint to learn about which
user and scopes are permitted for the token.

#### Request Parameters

- `token`: A token string received from a client

#### Response

A valid request will return JSON with these properties:

- `user`: The uid of the respective user.
- `scopes`: An array of scopes allowed for this token.

Example:

```js
{
  "user": "<PASSWORD>",
  "scopes": ["profile:email", "profile:avatar"]
}
```

[redirect]: #get-v1authorization
[authorization]: #post-v1authorization
[token]: #post-v1token
[verify]: #post-v1verify<commit_msg>fix broken ref links in docs<commit_after># Firefox Accounts OAuth Server API

## Overview

### URL Structure

```
https://<server-url>/v1/<api-endpoint>
```

Note that:

- All API access must be over HTTPS
- The URL embeds a version identifier "v1"; future revisions of this API may introduce new version numbers.
- The base URL of the server may be configured on a per-client basis

### Errors

Invalid requests will return 4XX responses. Internal failures will return 5XX. Both will include JSON responses describing the error.

Example error:

```js
{
  "code": 400, // matches the HTTP status code
  "errno": 101, // stable application-level error number
  "error": "Bad Request", // string description of error type
  "message": "Unknown client"
}
```

The currently-defined error responses are:

- status code, errno: description
- 400, 101: unknown client id
- 400, 102: incorrect client secret
- 400, 103: redirect_uri doesn't match registered value
- 400, 104: invalid fxa assertion 
- 400, 105: unknown code
- 400, 106: incorrect code
- 400, 107: expired code
- 400, 108: invalid token
- 400, 109: invalid request parameter
- 500, 999: internal server error

## API Endpoints


- [GET /v1/authorization][redirect]
- [POST /v1/authorization][authorization]
- [POST /v1/token][token]
- [GET /v1/client/:id][client]
- [POST /v1/verify][verify]

### GET /v1/client/:id

This endpoint is for the fxa-content-server to retreive information
about a client to show in its user interface.

#### Request Parameters

- `id`: The `client_id` of a client asking for permission.

Example:

```
https://oauth.accounts.firefox.com/v1/client/5901bd09376fadaa076afacef5251b6a
```

#### Response

A valid 200 response will be a JSON blob with the following properties:

- `name`: A string name of the client.
- `image_uri`: A url to a logo or image that represents the client.
- `redirect_uri`: The url registered to redirect to after successful oauth.

Example:

```js
{
  "name": "Where's My Fox",
  "image_uri": "https://mozilla.org/firefox.png",
  "redirect_uri": "https://wheres.my.firefox.com/oauth"
}
```

### GET /v1/authorization

This endpoint starts the OAuth flow. A client redirects the user agent
to this url. This endpoint will then redirect to the appropriate
content-server page.

### POST /v1/authorization

This endpoint should be used by the fxa-content-server, requesting that
we supply a short-lived code (currently 15 minutes) that will be sent
back to the client. This code will be traded for a token at the
[token][] endpoint.

#### Request Parameters

- `client_id`: The id returned from client registration.
- `assertion`: A FxA assertion for the signed-in user.
- `state`: A value that will be returned to the client as-is upon redirection, so that clients can verify the redirect is authentic.
- `redirect_uri`: Optional. If supplied, a string URL of where to redirect afterwards. Must match URL from registration.
- `scope`: Optional. A string-separated list of scopes that the user has authorized. This could be pruned by the user at the confirmation dialog.

#### Response

A valid request will return a 200 response, with JSON containing the `redirect` to follow. It will include the following query parameters:

- `code`: A string that the client will trade with the [token][] endpoint. Codes have a configurable expiration value, default is 15 minutes.
- `state`: The same value as was passed as a request parameter.

Example:

```js
{
  "redirect": "https://example.domain/path?foo=bar&code=asdfqwerty&state=zxcvasdf"
}
```

### POST /v1/token

After having received a [code][authorization], the client sends that code (most
likely a server-side request) to this endpoint, to receive a
longer-lived token that can be used to access attached services for a
particular user.

#### Request Parameters

- `client_id`: The id returned from client registration.
- `client_secret`: The secret returned from client registration.
- `code`: A string that was received from the [authorization][] endpoint.

#### Response

A valid request will return a JSON response with these properties:

- `access_token`: A string that can be used for authorized requests to service providers.
- `scope`: A string of space-separated permissions that this token has. May differ from requested scopes, since user can deny permissions.
- `token_type`: A string representing the token type. Currently will always be "bearer".

Example:

```js
{
  "access_token": "5<PASSWORD>",
  "scopes": [],
  "token_type": "bearer"
}
```

### POST /v1/verify

Attached services can post tokens to this endpoint to learn about which
user and scopes are permitted for the token.

#### Request Parameters

- `token`: A token string received from a client

#### Response

A valid request will return JSON with these properties:

- `user`: The uid of the respective user.
- `scopes`: An array of scopes allowed for this token.

Example:

```js
{
  "user": "<PASSWORD>",
  "scopes": ["profile:email", "profile:avatar"]
}
```

[client]: #get-v1client
[redirect]: #get-v1authorization
[authorization]: #post-v1authorization
[token]: #post-v1token
[verify]: #post-v1verify
{'fraction_non_alphanumeric': 0.10452859652547336, 'fraction_numerical': 0.022154987312121805, 'mean_word_length': 4.252178370066632, 'pattern_counts': {'":': 26, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 10, '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': '703197', 'n_tokens_mistral': 3185, 'n_tokens_neox': 2893, 'n_words': 1320}