Auth

Session

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

Login prerequisite

GET

https://peertube2.cpy.re/api/v1/oauth-clients/local

You need to retrieve a client id and secret before logging in.

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

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

200

{
  "client_id": "v1ikx5hnfop4mdpnci8nsqh93c45rldf",
  "client_secret": "AjWiOapPltI6EnsWQwlFarRtLh4u8tDt"
}

Response

200OKOAuthClient

successful operation

Response fields application/json

client_idstring

Example

v1ikx5hnfop4mdpnci8nsqh93c45rldf

client_secretstring

Example

AjWiOapPltI6EnsWQwlFarRtLh4u8tDt

Login

POST

https://peertube2.cpy.re/api/v1/users/token

With your client id and secret, you can retrieve an access and refresh tokens.

## 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"

Request Body

{
  "client_id": "v1ikx5hnfop4mdpnci8nsqh93c45rldf",
  "client_secret": "AjWiOapPltI6EnsWQwlFarRtLh4u8tDt",
  "grant_type": "password",
  "username": "chocobozzz",
  "password": "********",
  "externalAuthToken": "string"
}

200

{
  "token_type": "Bearer",
  "access_token": "90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0",
  "refresh_token": "2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7",
  "expires_in": 14399,
  "refresh_token_expires_in": 1209600
}

Body

application/x-www-form-urlencoded

One of

client_idstringrequired

Example

v1ikx5hnfop4mdpnci8nsqh93c45rldf

client_secretstringrequired

Example

AjWiOapPltI6EnsWQwlFarRtLh4u8tDt

grant_typestringpasswordrequired

usernameusernamerequired

immutable name of the user, used to find or mention its actor

Example

chocobozzz

passwordpassword<password>

externalAuthTokenstring

If you want to authenticate using an external authentication token you got from an auth plugin (like peertube-plugin-auth-openid-connect for example) instead of a password or a refresh token, provide it here.

client_idstringrequired

Example

v1ikx5hnfop4mdpnci8nsqh93c45rldf

client_secretstringrequired

Example

AjWiOapPltI6EnsWQwlFarRtLh4u8tDt

grant_typestringrefresh_tokenrequired

refresh_tokenstringrequired

Example

2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7

Parameters

x-peertube-otpstringheader

If the user enabled two factor authentication, you need to provide the OTP code in this header

Response

200OKobject

successful operation

Response fields application/json

token_typestring

Example

Bearer

access_tokenstring

valid for 1 day

Example

90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0

refresh_tokenstring

valid for 2 weeks

Example

2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7

expires_ininteger>= 0

Example

refresh_token_expires_ininteger>= 0

Example

400Bad Request

Disambiguate via code:

invalid_client for an unmatched client_id
invalid_grant for unmatched credentials

401Unauthorized

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

Logout

POST

https://peertube2.cpy.re/api/v1/users/revoke-token

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

Logout

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

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();

import requests

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

Response

200OK

successful operation

Authorization

OAuth2oauth2

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.

List token sessions

GET

https://peertube2.cpy.re/api/v1/users/{id}/token-sessions

List token sessions

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

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();

import requests

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

200

{
  "total": 1,
  "data": [
    {
      "id": 0,
      "currentSession": true,
      "loginDevice": "string",
      "loginIP": "192.168.1.1",
      "loginDate": "2024-01-15T09:30:00Z",
      "lastActivityDevice": "string",
      "lastActivityIP": "192.168.1.1",
      "lastActivityDate": "2024-01-15T09:30:00Z",
      "createdAt": "2024-01-15T09:30:00Z"
    }
  ]
}

Parameters

idid>= 1requiredpath

Entity id

Response

200OKobject

successful operation

Response fields application/json

totalinteger

Example

dataArray<TokenSession>

Show child attributes

idinteger

currentSessionboolean

Is this session the current one?

loginDevicestring

Device used to login

loginIPstring<ipv4>

IP address used to login

loginDatestring<date-time>

Date of the login

lastActivityDevicestring

lastActivityIPstring<ipv4>

lastActivityDatestring<date-time>

createdAtstring<date-time>

Authorization

OAuth2oauth2

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.

Revoke a token session

POST

https://peertube2.cpy.re/api/v1/users/{id}/token-sessions/{tokenSessionId}/revoke

Revoke a token session

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

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();

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)

Parameters

idid>= 1requiredpath

Entity id

tokenSessionIdid>= 1requiredpath

Token session Id

Response

200OK

successful operation

Authorization

OAuth2oauth2

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.

Docs by Sourcey