# Session

Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.


## Login prerequisite

`GET /api/v1/oauth-clients/local`

You need to retrieve a client id and secret before [logging in](https://docs.joinpeertube.org/api-rest-reference/api/operations/getoauthtoken.html).

Authentication: no security requirement declared for this operation.

Responses:

- 200: successful operation

Content type: application/json

Type: OAuthClient

Schema: [OAuthClient](https://docs.joinpeertube.org/api-rest-reference/api/models/oauthclient.md)

- `client_id` (optional)
  Type: string
  
  minLength: 32
  
  maxLength: 32
  
  pattern: "/^[a-z0-9]$/"
  
  Example:
  
  ```json
  "v1ikx5hnfop4mdpnci8nsqh93c45rldf"
  ```

- `client_secret` (optional)
  Type: string
  
  minLength: 32
  
  maxLength: 32
  
  pattern: "/^[a-zA-Z0-9]$/"
  
  Example:
  
  ```json
  "AjWiOapPltI6EnsWQwlFarRtLh4u8tDt"
  ```

## Examples

### Shell

```Shell
API="https://peertube2.cpy.re/api/v1"

## AUTH
curl -s "$API/oauth-clients/local"
```


## Login

`POST /api/v1/users/token`

With your [client id and secret](https://docs.joinpeertube.org/api-rest-reference/api/operations/getoauthclient.html), you can retrieve an access and refresh tokens.

Authentication: no security requirement declared for this operation.

Parameters:

- `x-peertube-otp` (header, string, optional) - If the user enabled two factor authentication, you need to provide the OTP code in this header
  Type: string

Request body: application/x-www-form-urlencoded

Type: OAuthClient & object

Discriminator:

```json
{
  "propertyName": "grant_type",
  "mapping": {
    "password": "#/components/schemas/OAuthToken-password",
    "refresh_token": "#/components/schemas/OAuthToken-refresh_token"
  }
}
```

oneOf:
  Reference: [OAuthToken-password](https://docs.joinpeertube.org/api-rest-reference/api/models/oauthtoken-password.md); Type: OAuthClient & object

  Reference: [OAuthToken-refresh_token](https://docs.joinpeertube.org/api-rest-reference/api/models/oauthtoken-refresh-token.md); Type: OAuthClient & object

Responses:

- 200: successful operation

Content type: application/json

Type: object

- `token_type` (optional)
  Type: string
  
  Example:
  
  ```json
  "Bearer"
  ```

- `access_token` (optional)
  Type: string
  
  valid for 1 day
  
  Example:
  
  ```json
  "90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0"
  ```

- `refresh_token` (optional)
  Type: string
  
  valid for 2 weeks
  
  Example:
  
  ```json
  "2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7"
  ```

- `expires_in` (optional)
  Type: integer
  
  minimum: 0
  
  Example:
  
  ```json
  14399
  ```

- `refresh_token_expires_in` (optional)
  Type: integer
  
  minimum: 0
  
  Example:
  
  ```json
  1209600
  ```

- 400: Disambiguate via `code`:
- `invalid_client` for an unmatched `client_id`
- `invalid_grant` for unmatched credentials


- 401: Disambiguate via `code`:
- default value for a regular authentication failure
- `invalid_token` for an expired token
- `missing_two_factor` if two factor header is missing


## Examples

### Shell

```Shell
## DEPENDENCIES: jq
API="https://peertube2.cpy.re/api/v1"
USERNAME="<your_username>"
PASSWORD="<your_password>"

## AUTH
client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
curl -s "$API/users/token" \
  --data client_id="$client_id" \
  --data client_secret="$client_secret" \
  --data grant_type=password \
  --data username="$USERNAME" \
  --data-urlencode password="$PASSWORD" \
  | jq -r ".access_token"
```


## Logout

`POST /api/v1/users/revoke-token`

Revokes your access token and its associated refresh token, destroying your current session.

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. Authenticating via OAuth requires the following steps:
- Have an activated account
- [Generate] an access token for that account at `/api/v1/users/token`.
- Make requests with the *Authorization: Bearer <token\>* header
- Profit, depending on the role assigned to the account

Note that the __access token is valid for 1 day__ and is given
along with a __refresh token valid for 2 weeks__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Responses:

- 200: successful operation

## Examples

### cURL

```bash
curl -X POST 'https://peertube2.cpy.re/api/v1/users/revoke-token' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/users/revoke-token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/revoke-token',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List token sessions

`GET /api/v1/users/{id}/token-sessions`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. Authenticating via OAuth requires the following steps:
- Have an activated account
- [Generate] an access token for that account at `/api/v1/users/token`.
- Make requests with the *Authorization: Bearer <token\>* header
- Profit, depending on the role assigned to the account

Note that the __access token is valid for 1 day__ and is given
along with a __refresh token valid for 2 weeks__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id, required) - Entity id
  Type: id
  
  Schema: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md)
  
  minimum: 1
  
  Example:
  
  ```json
  42
  ```

Responses:

- 200: successful operation

Content type: application/json

Type: object

- `total` (optional)
  Type: integer
  
  Example:
  
  ```json
  1
  ```

- `data` (optional)
  Type: Array<TokenSession>
  
  Items:
    Reference: [TokenSession](https://docs.joinpeertube.org/api-rest-reference/api/models/tokensession.md); Type: TokenSession

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/users/42/token-sessions' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/users/42/token-sessions', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://peertube2.cpy.re/api/v1/users/42/token-sessions',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Revoke a token session

`POST /api/v1/users/{id}/token-sessions/{tokenSessionId}/revoke`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. Authenticating via OAuth requires the following steps:
- Have an activated account
- [Generate] an access token for that account at `/api/v1/users/token`.
- Make requests with the *Authorization: Bearer <token\>* header
- Profit, depending on the role assigned to the account

Note that the __access token is valid for 1 day__ and is given
along with a __refresh token valid for 2 weeks__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id, required) - Entity id
  Type: id
  
  Schema: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md)
  
  minimum: 1
  
  Example:
  
  ```json
  42
  ```

- `tokenSessionId` (path, id, required) - Token session Id
  Type: id
  
  Schema: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md)
  
  minimum: 1
  
  Example:
  
  ```json
  42
  ```

Responses:

- 200: successful operation

## Examples

### cURL

```bash
curl -X POST 'https://peertube2.cpy.re/api/v1/users/42/token-sessions/42/revoke' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/users/42/token-sessions/42/revoke', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/42/token-sessions/42/revoke',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```