Auth

Register

As a visitor, you can use this API to open an account (if registrations are open on that PeerTube instance). As an admin, you should use the dedicated User creation API instead.

Resend user verification link

POST

https://peertube2.cpy.re/api/v1/users/ask-send-verify-email

Resend user verification link

curl -X POST 'https://peertube2.cpy.re/api/v1/users/ask-send-verify-email' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "string"
}'

const body = `{
  "email": "string"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/users/ask-send-verify-email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "email": "string"
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/ask-send-verify-email',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "email": "string"
}

Body

application/json

emailstringrequired

User email

Response

204No Content

successful operation

Resend verification link to registration request email

POST

https://peertube2.cpy.re/api/v1/users/registrations/ask-send-verify-email

Resend verification link to registration request email

curl -X POST 'https://peertube2.cpy.re/api/v1/users/registrations/ask-send-verify-email' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "string"
}'

const body = `{
  "email": "string"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/users/registrations/ask-send-verify-email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "email": "string"
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/registrations/ask-send-verify-email',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "email": "string"
}

Body

application/json

emailstringrequired

Registration email

Response

204No Content

successful operation

Verify a user

POST

https://peertube2.cpy.re/api/v1/users/{id}/verify-email

Following a user registration, the new user will receive an email asking to click a link containing a secret. This endpoint can also be used to verify a new email set in the user account.

Verify a user

curl -X POST 'https://peertube2.cpy.re/api/v1/users/42/verify-email' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "verificationString": "https://example.com",
  "isPendingEmail": true
}'

const body = `{
  "verificationString": "https://example.com",
  "isPendingEmail": true
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/users/42/verify-email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "verificationString": "https://example.com",
  "isPendingEmail": true
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/42/verify-email',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "verificationString": "https://example.com",
  "isPendingEmail": true
}

Body

application/json

verificationStringstring<url>required

isPendingEmailboolean

Parameters

idid>= 1requiredpath

Entity id

Response

204No Content

successful operation

403Forbidden

invalid verification string

404Not Found

user not found

Verify a registration email

POST

https://peertube2.cpy.re/api/v1/users/registrations/{registrationId}/verify-email

Following a user registration request, the user will receive an email asking to click a link containing a secret.

Verify a registration email

curl -X POST 'https://peertube2.cpy.re/api/v1/users/registrations/42/verify-email' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "verificationString": "https://example.com"
}'

const body = `{
  "verificationString": "https://example.com"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/users/registrations/42/verify-email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "verificationString": "https://example.com"
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/registrations/42/verify-email',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "verificationString": "https://example.com"
}

Body

application/json

verificationStringstring<url>required

Parameters

registrationIdid>= 1requiredpath

Registration ID

Response

204No Content

successful operation

403Forbidden

invalid verification string

404Not Found

registration not found

Register a user

POST

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

Signup has to be enabled and signup approval is not required

curl -X POST 'https://peertube2.cpy.re/api/v1/users/register' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "password": "********",
  "email": "user@example.com",
  "displayName": "string",
  "channel": {
    "name": "framasoft_videos",
    "displayName": "string"
  },
  "signupClient": "peertube-app"
}'

const body = `{
  "password": "********",
  "email": "user@example.com",
  "displayName": "string",
  "channel": {
    "name": "framasoft_videos",
    "displayName": "string"
  },
  "signupClient": "peertube-app"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/users/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "password": "********",
  "email": "user@example.com",
  "displayName": "string",
  "channel": {
    "name": "framasoft_videos",
    "displayName": "string"
  },
  "signupClient": "peertube-app"
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/register',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "password": "********",
  "email": "user@example.com",
  "displayName": "string",
  "channel": {
    "name": "framasoft_videos",
    "displayName": "string"
  },
  "signupClient": "peertube-app"
}

200

{
  "state": {
    "id": 1,
    "label": "string"
  }
}

Body

application/json

usernameusernamerequired

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

Show child attributes

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

username

Example

chocobozzz

passwordpassword<password>required

emailstring<email>required

email of the user, used for login or service communications

displayNamestring

editable name of the user, displayed in its representations

channelobject

channel base information used to create the first channel of the user

Show child attributes

nameusernameChannel

immutable name of the channel, used to interact with its actor

Example

framasoft_videos

displayNamestring

signupClientstringpeertube-app

PeerTube >= 9.0 Client used to sign up. If set, links of the verification and registration accepted emails make the web client propose to open this client

Response

200OKobject

successful operation

Response fields application/json

stateobject

Show child attributes

idUserRegistrationState123

The registration state (Pending = 1, Rejected = 2, Accepted = 3)

labelstring

400Bad Request

request error

403Forbidden

user registration is not enabled, user limit is reached, registration is not allowed for the ip, requires approval or blocked by a plugin

409Conflict

a user with this username, channel name or email already exists

Request registration

POST

https://peertube2.cpy.re/api/v1/users/registrations/request

Signup has to be enabled and require approval on the instance

Request registration

curl -X POST 'https://peertube2.cpy.re/api/v1/users/registrations/request' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "password": "********",
  "email": "user@example.com",
  "displayName": "string",
  "channel": {
    "name": "framasoft_videos",
    "displayName": "string"
  },
  "signupClient": "peertube-app",
  "registrationReason": "string"
}'

const body = `{
  "password": "********",
  "email": "user@example.com",
  "displayName": "string",
  "channel": {
    "name": "framasoft_videos",
    "displayName": "string"
  },
  "signupClient": "peertube-app",
  "registrationReason": "string"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/users/registrations/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "password": "********",
  "email": "user@example.com",
  "displayName": "string",
  "channel": {
    "name": "framasoft_videos",
    "displayName": "string"
  },
  "signupClient": "peertube-app",
  "registrationReason": "string"
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/registrations/request',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "password": "********",
  "email": "user@example.com",
  "displayName": "string",
  "channel": {
    "name": "framasoft_videos",
    "displayName": "string"
  },
  "signupClient": "peertube-app",
  "registrationReason": "string"
}

200

{
  "state": {
    "id": 1,
    "label": "string"
  }
}

Body

application/json

usernameusernamerequired

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

Show child attributes

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

username

Example

chocobozzz

passwordpassword<password>required

emailstring<email>required

email of the user, used for login or service communications

displayNamestring

editable name of the user, displayed in its representations

channelobject

channel base information used to create the first channel of the user

Show child attributes

nameusernameChannel

immutable name of the channel, used to interact with its actor

Example

framasoft_videos

displayNamestring

signupClientstringpeertube-app

PeerTube >= 9.0 Client used to sign up. If set, links of the verification and registration accepted emails make the web client propose to open this client

registrationReasonstringrequired

reason for the user to register on the instance

Response

200OKobject

successful operation

Response fields application/json

stateobject

Show child attributes

idUserRegistrationState123

The registration state (Pending = 1, Rejected = 2, Accepted = 3)

labelstring

400Bad Request

request error or signup approval is not enabled on the instance

403Forbidden

user registration is not enabled, user limit is reached, registration is not allowed for the ip or blocked by a plugin

409Conflict

a user or registration with this username, channel name or email already exists

Accept registration

POST

https://peertube2.cpy.re/api/v1/users/registrations/{registrationId}/accept

Accept registration

curl -X POST 'https://peertube2.cpy.re/api/v1/users/registrations/42/accept' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "moderationResponse": "string",
  "preventEmailDelivery": true
}'

const body = `{
  "moderationResponse": "string",
  "preventEmailDelivery": true
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/users/registrations/42/accept', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "moderationResponse": "string",
  "preventEmailDelivery": true
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/registrations/42/accept',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "moderationResponse": "string",
  "preventEmailDelivery": true
}

Body

application/json

moderationResponsestringrequired

Moderation response to send to the user

preventEmailDeliveryboolean

Set it to true if you don't want PeerTube to send an email to the user

Parameters

registrationIdid>= 1requiredpath

Registration ID

Response

204No Content

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.

Scopes: admin, moderator

Reject registration

POST

https://peertube2.cpy.re/api/v1/users/registrations/{registrationId}/reject

Reject registration

curl -X POST 'https://peertube2.cpy.re/api/v1/users/registrations/42/reject' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "moderationResponse": "string",
  "preventEmailDelivery": true
}'

const body = `{
  "moderationResponse": "string",
  "preventEmailDelivery": true
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/users/registrations/42/reject', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "moderationResponse": "string",
  "preventEmailDelivery": true
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/users/registrations/42/reject',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "moderationResponse": "string",
  "preventEmailDelivery": true
}

Body

application/json

moderationResponsestringrequired

Moderation response to send to the user

preventEmailDeliveryboolean

Set it to true if you don't want PeerTube to send an email to the user

Parameters

registrationIdid>= 1requiredpath

Registration ID

Response

204No Content

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.

Scopes: admin, moderator

Delete registration

DELETE

https://peertube2.cpy.re/api/v1/users/registrations/{registrationId}

Delete the registration entry. It will not remove the user associated with this registration (if any)

Delete registration

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

const response = await fetch('https://peertube2.cpy.re/api/v1/users/registrations/42', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

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

Parameters

registrationIdid>= 1requiredpath

Registration ID

Response

204No Content

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.

Scopes: admin, moderator

List registrations

GET

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

List registrations

curl -X GET 'https://peertube2.cpy.re/api/v1/users/registrations?count=15' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/users/registrations?count=15', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://peertube2.cpy.re/api/v1/users/registrations?count=15',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "id": 42,
      "state": {
        "id": 1,
        "label": "string"
      },
      "registrationReason": "string",
      "moderationResponse": "string",
      "username": "string",
      "email": "user@example.com",
      "emailVerified": true,
      "accountDisplayName": "string",
      "channelHandle": "string",
      "channelDisplayName": "string",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z",
      "user": {
        "id": 42
      }
    }
  ]
}

Parameters

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

searchstringquery

sortstring-createdAtcreatedAtstate-statequery

stateOneOfArray<UserRegistrationState>123query

Response

200OKobject

successful operation

Response fields application/json

totalinteger

Example

dataArray<UserRegistration>

Show child attributes

idid>= 1

Example

stateobject

Show child attributes

idUserRegistrationState123

The registration state (Pending = 1, Rejected = 2, Accepted = 3)

labelstring

registrationReasonstring

moderationResponsestring | null

usernamestring

emailstring<email>

emailVerifiedboolean

accountDisplayNamestring

channelHandlestring

channelDisplayNamestring

createdAtstring<date-time>

updatedAtstring<date-time>

userobject | null

If the registration has been accepted, this is a partial user object created by the registration

Show child attributes

idid>= 1

Example

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.

Scopes: admin, moderator

Docs by Sourcey