IcyNet.eu/API.md

# IcyNet.eu API Documentation

## `/oauth2`
OAuth 2.0 Authorization endpoints

### `GET /authorize` **+session**
OAuth 2.0 Authorization dialog.

The following query parameters are expected:
* `redirect_uri` - Client redirection URI, must match the redirection URI defined by client.
* `client_id` - Client redirection ID.
* `response_type` - Response type. Pretty much always `code`.
* `scope` *(optional)* - Request additional resources. Available scopes are: `privilege`, `email`, `image`.
* `state` *(optional)* - A forwarded token to prevent request forgery.

### `POST /token`
Get an Access Token from `code`.

The following must be passed in the request body:
* `grant_type` - One of `authorization_code`, `client_credentials` or `refresh_token`.
* `scope` *(optional)* - See `/authorize`.

Successful response:
```
{
    token_type: 'bearer',
    access_token: <access token>,
    [refresh_token: <refresh token>,]
    expires_in: <seconds till token expiry>
}
```

A `Authorization: Basic base64(client_id:client_secret)` header must be present **OR** `client_id` and `client_secret` can also be passed in the request body. Both variants are supported by the API.

### `POST /introspect`
Check for the validity of an Access Token.

The following must be passed in the request body:
* `token` - The Access Token to introspect.

Successful response:
```
{
    token_type: 'bearer',
    token: <access token>,
    expires_in: <seconds till token expiry>
}
```

Requires client authentication, see `POST /token`.

### `GET /user`
Get user information using an access token. Access token can be provided via querystring or header.

Successful response:
```
{
    id: <user id>,
    uuid: <user uuid>,
    username: <user username>,
    display_name: <user display_name>,
    [email: <user email address>] (requires email scope),
    [image: <URL to user's avatar file>] (requires image scope),
    [privilege: <user privilege level>] (requires privilege scope)
}
```

## `/api`
Internal API endpoints.

### `/external`
Authentication callbacks.

### `GET /news`
Icy Network News.

#### `GET /news/:id`
Get a news article by it's ID.

#### `POST /news/edit/:id` **+session**
Edit a news article by it's ID. **Requires a special privileged user**

#### `GET /news/all/:page`
Get all news articles on `:page`.

### `POST /avatar` **+session**
Change the avatar of the currently logged in user.

#### `POST /remove` **+session**
Remove the avatar of the currently logged in user.

#### `POST /gravatar` **+session**
Set the avatar of the currently logged in user to their Gravatar avatar.

### `GET /avatar` **+session**
Get the avatar of the currently logged in user.

#### `GET /gravatar` **+session**
Get the Gravatar avatar of the currently logged in user, if applicable.

#### `GET /:id`
Get the avatar of the user with ID `:id`.

### `/oauth2`
Special OAuth 2.0 management endpoints.

#### `GET /authorized-clients` **+session**
Get the authorized OAuth 2.0 clients of the currently logged in user.

##### `POST /revoke` **+session**
Revoke an authorized OAuth 2.0 client. Requires `client_id` in the body.

### `GET /donations`
List the donations given to Icy Network.

#### `GET /user` **+session**
List the donations given to Icy Network by the currently logged in user.

### `POST /paypal/ipn`
PayPal Payment Notification endpoint.