# 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](https://docs.joinpeertube.org/api-rest-reference/api/operations/adduser.html) instead.


## Resend user verification link

`POST /api/v1/users/ask-send-verify-email`

Authentication: no security requirement declared for this operation.

Request body: application/json

Type: object

- `email` (required)
  Type: string
  
  User email

Responses:

- 204: successful operation

## Examples

### cURL

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

### JavaScript

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

### Python

```python
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)
```


## Resend verification link to registration request email

`POST /api/v1/users/registrations/ask-send-verify-email`

Authentication: no security requirement declared for this operation.

Request body: application/json

Type: object

- `email` (required)
  Type: string
  
  Registration email

Responses:

- 204: successful operation

## Examples

### cURL

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

### JavaScript

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

### Python

```python
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)
```


## Verify a user

`POST /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.


Authentication: no security requirement declared for this operation.

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
  ```

Request body: application/json

Type: object

- `verificationString` (required)
  Type: string, url

- `isPendingEmail` (optional)
  Type: boolean

Responses:

- 204: successful operation

- 403: invalid verification string

- 404: user not found

## Examples

### cURL

```bash
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
}'
```

### JavaScript

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

### Python

```python
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)
```


## Verify a registration email

`POST /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.


Authentication: no security requirement declared for this operation.

Parameters:

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

Request body: application/json

Type: object

- `verificationString` (required)
  Type: string, url

Responses:

- 204: successful operation

- 403: invalid verification string

- 404: registration not found

## Examples

### cURL

```bash
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"
}'
```

### JavaScript

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

### Python

```python
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)
```


## Register a user

`POST /api/v1/users/register`

Signup has to be enabled and signup approval is not required

Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: RegisterUser

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

- `username` (required)
  Type: username
  
  immutable name of the user, used to find or mention its actor
  
  allOf:
    Reference: [username](https://docs.joinpeertube.org/api-rest-reference/api/models/username.md); Type: username
    
    immutable name of the user, used to find or mention its actor
    
    minLength: 1
    
    maxLength: 50
    
    pattern: "/^[a-z0-9._]+$/"
    
    Example:
    
    ```json
    "chocobozzz"
    ```

- `password` (required)
  Reference: [password](https://docs.joinpeertube.org/api-rest-reference/api/models/password.md); Type: password, password
  
  minLength: 6
  
  maxLength: 50

- `email` (required)
  Type: string, email
  
  email of the user, used for login or service communications

- `displayName` (optional)
  Type: string
  
  editable name of the user, displayed in its representations
  
  minLength: 1
  
  maxLength: 120

- `channel` (optional)
  Type: object
  
  channel base information used to create the first channel of the user
  
  - `name` (optional)
    Reference: [usernameChannel](https://docs.joinpeertube.org/api-rest-reference/api/models/usernamechannel.md); Type: usernameChannel
    
    immutable name of the channel, used to interact with its actor
    
    minLength: 1
    
    maxLength: 50
    
    pattern: "/^[a-zA-Z0-9\\\\-_.:]+$/"
    
    Example:
    
    ```json
    "framasoft_videos"
    ```
  
  - `displayName` (optional)
    Type: string

- `signupClient` (optional)
  Type: string
  
  **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
  
  
  enum: ["peertube-app"]

Responses:

- 200: successful operation

Content type: application/json

Type: object

- `state` (optional)
  Type: object
  
  - `id` (optional)
    Reference: [UserRegistrationState](https://docs.joinpeertube.org/api-rest-reference/api/models/userregistrationstate.md); Type: UserRegistrationState
    
    The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)
    
    enum: [1,2,3]
  
  - `label` (optional)
    Type: string

- 400: request error

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

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

## Examples

### cURL

```bash
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"
}'
```

### JavaScript

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

### Python

```python
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 registration

`POST /api/v1/users/registrations/request`

Signup has to be enabled and require approval on the instance

Authentication: no security requirement declared for this operation.

Request body: application/json

Type: RegisterUser & object

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

allOf:
  Reference: [RegisterUser](https://docs.joinpeertube.org/api-rest-reference/api/models/registeruser.md); Type: RegisterUser

  Type: object
  
  - `registrationReason` (required)
    Type: string
    
    reason for the user to register on the instance

Responses:

- 200: successful operation

Content type: application/json

Type: object

- `state` (optional)
  Type: object
  
  - `id` (optional)
    Reference: [UserRegistrationState](https://docs.joinpeertube.org/api-rest-reference/api/models/userregistrationstate.md); Type: UserRegistrationState
    
    The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)
    
    enum: [1,2,3]
  
  - `label` (optional)
    Type: string

- 400: request error or signup approval is not enabled on the instance

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

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

## Examples

### cURL

```bash
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"
}'
```

### JavaScript

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

### Python

```python
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)
```


## Accept registration

`POST /api/v1/users/registrations/{registrationId}/accept`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": [
      "admin",
      "moderator"
    ]
  }
]
```

- 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
; scopes: admin, moderator

Parameters:

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

Request body: application/json

Type: UserRegistrationAcceptOrReject

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

- `moderationResponse` (required)
  Type: string
  
  Moderation response to send to the user

- `preventEmailDelivery` (optional)
  Type: boolean
  
  Set it to true if you don't want PeerTube to send an email to the user

Responses:

- 204: successful operation

## Examples

### cURL

```bash
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
}'
```

### JavaScript

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

### Python

```python
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)
```


## Reject registration

`POST /api/v1/users/registrations/{registrationId}/reject`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": [
      "admin",
      "moderator"
    ]
  }
]
```

- 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
; scopes: admin, moderator

Parameters:

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

Request body: application/json

Type: UserRegistrationAcceptOrReject

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

- `moderationResponse` (required)
  Type: string
  
  Moderation response to send to the user

- `preventEmailDelivery` (optional)
  Type: boolean
  
  Set it to true if you don't want PeerTube to send an email to the user

Responses:

- 204: successful operation

## Examples

### cURL

```bash
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
}'
```

### JavaScript

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

### Python

```python
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)
```


## Delete registration

`DELETE /api/v1/users/registrations/{registrationId}`

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

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": [
      "admin",
      "moderator"
    ]
  }
]
```

- 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
; scopes: admin, moderator

Parameters:

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

Responses:

- 204: successful operation

## Examples

### cURL

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

### JavaScript

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

### Python

```python
import requests

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


## List registrations

`GET /api/v1/users/registrations`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": [
      "admin",
      "moderator"
    ]
  }
]
```

- 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
; scopes: admin, moderator

Parameters:

- `start` (query, integer, optional) - Offset used to paginate results
  Type: integer
  
  minimum: 0

- `count` (query, integer, optional) - Number of items to return
  Type: integer
  
  default: 15
  
  minimum: 1
  
  maximum: 100

- `search` (query, string, optional)
  Type: string

- `sort` (query, string, optional)
  Type: string
  
  enum: ["-createdAt","createdAt","state","-state"]

- `stateOneOf` (query, Array<UserRegistrationState>, optional)
  Type: Array<UserRegistrationState>
  
  Items:
    Reference: [UserRegistrationState](https://docs.joinpeertube.org/api-rest-reference/api/models/userregistrationstate.md); Type: UserRegistrationState
    
    The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)
    
    enum: [1,2,3]

Responses:

- 200: successful operation

Content type: application/json

Type: object

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

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

## Examples

### cURL

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

### JavaScript

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

### Python

```python
import requests

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