aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/api
diff options
context:
space:
mode:
authorRigel Kent <sendmemail@rigelk.eu>2021-05-12 21:23:54 +0200
committerRigel Kent <sendmemail@rigelk.eu>2021-05-12 21:49:00 +0200
commite2464d22a5f19168022e72c77e82019726216542 (patch)
tree9fcd6fd0b32540be8d561f051976f57f984d5d70 /support/doc/api
parent0ae3ebb03edf8b6a6d74666f006d7373e393e40d (diff)
downloadPeerTube-e2464d22a5f19168022e72c77e82019726216542.tar.gz
PeerTube-e2464d22a5f19168022e72c77e82019726216542.tar.zst
PeerTube-e2464d22a5f19168022e72c77e82019726216542.zip
add login/logout routes in openapi spec
Diffstat (limited to 'support/doc/api')
-rw-r--r--support/doc/api/openapi.yaml232
1 files changed, 213 insertions, 19 deletions
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index d8597d618..f54df1dd0 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -4,12 +4,12 @@ info:
4 version: 3.2.0-rc.1 4 version: 3.2.0-rc.1
5 contact: 5 contact:
6 name: PeerTube Community 6 name: PeerTube Community
7 url: 'https://joinpeertube.org' 7 url: https://joinpeertube.org
8 license: 8 license:
9 name: AGPLv3.0 9 name: AGPLv3.0
10 url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE' 10 url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
11 x-logo: 11 x-logo:
12 url: 'https://joinpeertube.org/img/brand.png' 12 url: https://joinpeertube.org/img/brand.png
13 altText: PeerTube Project Homepage 13 altText: PeerTube Project Homepage
14 description: | 14 description: |
15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite 15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
@@ -27,8 +27,8 @@ info:
27 # Authentication 27 # Authentication
28 28
29 When you sign up for an account on a PeerTube instance, you are given the possibility 29 When you sign up for an account on a PeerTube instance, you are given the possibility
30 to generate sessions on it, and authenticate there using a session token. Only __one 30 to generate sessions on it, and authenticate there using an access token. Only __one
31 session token can currently be used at a time__. 31 access token can currently be used at a time__.
32 32
33 ## Roles 33 ## Roles
34 34
@@ -91,18 +91,27 @@ info:
91 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/), 91 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
92 allowing cross-domain communication from the browser for some routes: 92 allowing cross-domain communication from the browser for some routes:
93 93
94 | Endpoint | Origin | 94 | Endpoint |
95 |------------------------- ---|--------| 95 |------------------------- ---|
96 | `/api/*` | * | 96 | `/api/*` |
97 | `/download/*` | * | 97 | `/download/*` |
98 | `/lazy-static/*` | * | 98 | `/lazy-static/*` |
99 | `/live/segments-sha256/*` | * | 99 | `/live/segments-sha256/*` |
100 | `/.well-known/webfinger` | * | 100 | `/.well-known/webfinger` |
101 101
102 In addition, all routes serving ActivityPub are CORS-enabled for all origins. 102 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
103externalDocs: 103externalDocs:
104 url: https://docs.joinpeertube.org/api-rest-reference.html 104 url: https://docs.joinpeertube.org/api-rest-reference.html
105tags: 105tags:
106 - name: Register
107 description: |
108 As a visitor, you can use this API to open an account (if registrations are open on
109 that PeerTube instance). As an admin, you should use the dedicated [User creation
110 API](#operation/createUser) instead.
111 - name: Session
112 x-displayName: Login/Logout
113 description: |
114 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
106 - name: Accounts 115 - name: Accounts
107 description: > 116 description: >
108 Accounts encompass remote accounts discovered across the federation, 117 Accounts encompass remote accounts discovered across the federation,
@@ -226,6 +235,10 @@ tags:
226 235
227 For importing videos as your own, refer to [video imports](#operation/importVideo). 236 For importing videos as your own, refer to [video imports](#operation/importVideo).
228x-tagGroups: 237x-tagGroups:
238 - name: Auth
239 tags:
240 - Register
241 - Session
229 - name: Accounts 242 - name: Accounts
230 tags: 243 tags:
231 - Accounts 244 - Accounts
@@ -573,6 +586,7 @@ paths:
573 /users: 586 /users:
574 post: 587 post:
575 summary: Create a user 588 summary: Create a user
589 operationId: createUser
576 security: 590 security:
577 - OAuth2: 591 - OAuth2:
578 - admin 592 - admin
@@ -689,11 +703,92 @@ paths:
689 schema: 703 schema:
690 $ref: '#/components/schemas/UpdateUser' 704 $ref: '#/components/schemas/UpdateUser'
691 required: true 705 required: true
706
707 /oauth-clients/local:
708 get:
709 summary: Login prerequisite
710 description: You need to retrieve a client id and secret before [logging in](#operation/getOauthToken).
711 operationId: getOAuthClient
712 tags:
713 - Session
714 responses:
715 '200':
716 description: successful operation
717 content:
718 application/json:
719 schema:
720 $ref: '#/components/schemas/OAuthClient'
721 links:
722 UseOAuthClientToLogin:
723 operationId: getOAuthToken
724 parameters:
725 client_id: '$response.body#/client_id'
726 client_secret: '$response.body#/client_secret'
727 /users/token:
728 post:
729 summary: Login
730 operationId: getOAuthToken
731 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
732 tags:
733 - Session
734 requestBody:
735 content:
736 application/x-www-form-urlencoded:
737 schema:
738 oneOf:
739 - $ref: '#/components/schemas/OAuthToken-password'
740 - $ref: '#/components/schemas/OAuthToken-refresh_token'
741 discriminator:
742 propertyName: grant_type
743 mapping:
744 password: '#/components/schemas/OAuthToken-password'
745 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
746 responses:
747 '200':
748 description: successful operation
749 content:
750 application/json:
751 schema:
752 type: object
753 properties:
754 token_type:
755 type: string
756 example: Bearer
757 access_token:
758 type: string
759 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
760 description: valid for 1 day
761 refresh_token:
762 type: string
763 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
764 description: valid for 2 weeks
765 expires_in:
766 type: integer
767 minimum: 0
768 example: 14399
769 refresh_token_expires_in:
770 type: integer
771 minimum: 0
772 example: 1209600
773 /users/revoke-token:
774 post:
775 summary: Logout
776 description: Revokes your access token and its associated refresh token, destroying your current session.
777 operationId: revokeOAuthToken
778 tags:
779 - Session
780 security:
781 - OAuth2: []
782 responses:
783 '200':
784 description: successful operation
785
692 /users/register: 786 /users/register:
693 post: 787 post:
694 summary: Register a user 788 summary: Register a user
695 tags: 789 tags:
696 - Users 790 - Users
791 - Register
697 responses: 792 responses:
698 '204': 793 '204':
699 description: successful operation 794 description: successful operation
@@ -703,6 +798,47 @@ paths:
703 schema: 798 schema:
704 $ref: '#/components/schemas/RegisterUser' 799 $ref: '#/components/schemas/RegisterUser'
705 required: true 800 required: true
801 /users/{id}/verify-email:
802 post:
803 summary: Verify a user
804 description: |
805 Following a user registration, the new user will receive an email asking to click a link
806 containing a secret.
807 tags:
808 - Users
809 - Register
810 parameters:
811 - $ref: '#/components/parameters/id'
812 requestBody:
813 content:
814 application/json:
815 schema:
816 type: object
817 properties:
818 verificationString:
819 type: string
820 format: url
821 isPendingEmail:
822 type: boolean
823 required:
824 - verificationString
825 responses:
826 '204':
827 description: successful operation
828 '403':
829 description: invalid verification string
830 '404':
831 description: user not found
832 /users/ask-send-verify-email:
833 post:
834 summary: Resend user verification link
835 tags:
836 - Users
837 - Register
838 responses:
839 '204':
840 description: successful operation
841
706 /users/me: 842 /users/me:
707 get: 843 get:
708 summary: Get my user information 844 summary: Get my user information
@@ -4225,17 +4361,18 @@ components:
4225 description: | 4361 description: |
4226 Authenticating via OAuth requires the following steps: 4362 Authenticating via OAuth requires the following steps:
4227 - Have an activated account 4363 - Have an activated account
4228 - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a 4364 - [Generate] an access token for that account at `/api/v1/users/token`.
4229 Bearer Token for that account at `/api/v1/users/token` 4365 - Make requests with the *Authorization: Bearer <token\>* header
4230 - Make authenticated requests, putting *Authorization: Bearer <token\>*
4231 - Profit, depending on the role assigned to the account 4366 - Profit, depending on the role assigned to the account
4232 4367
4233 Note that the __access token is valid for 1 day__ and, and is given 4368 Note that the __access token is valid for 1 day__ and is given
4234 along with a __refresh token valid for 2 weeks__. 4369 along with a __refresh token valid for 2 weeks__.
4370
4371 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4235 type: oauth2 4372 type: oauth2
4236 flows: 4373 flows:
4237 password: 4374 password:
4238 tokenUrl: 'https://peertube.example.com/api/v1/users/token' 4375 tokenUrl: /api/v1/users/token
4239 scopes: 4376 scopes:
4240 admin: Admin scope 4377 admin: Admin scope
4241 moderator: Moderator scope 4378 moderator: Moderator scope
@@ -4257,14 +4394,16 @@ components:
4257 type: string 4394 type: string
4258 description: immutable name of the user, used to find or mention its actor 4395 description: immutable name of the user, used to find or mention its actor
4259 example: chocobozzz 4396 example: chocobozzz
4260 pattern: '/^[a-z0-9._]{1,50}$/' 4397 pattern: '/^[a-z0-9._]+$/'
4261 minLength: 1 4398 minLength: 1
4262 maxLength: 50 4399 maxLength: 50
4263 usernameChannel: 4400 usernameChannel:
4264 type: string 4401 type: string
4265 description: immutable name of the channel, used to interact with its actor 4402 description: immutable name of the channel, used to interact with its actor
4266 example: framasoft_videos 4403 example: framasoft_videos
4267 pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/' 4404 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4405 minLength: 1
4406 maxLength: 50
4268 password: 4407 password:
4269 type: string 4408 type: string
4270 format: password 4409 format: password
@@ -5998,6 +6137,61 @@ components:
5998 - password 6137 - password
5999 - email 6138 - email
6000 6139
6140 OAuthClient:
6141 properties:
6142 client_id:
6143 type: string
6144 pattern: /^[a-z0-9]$/
6145 maxLength: 32
6146 minLength: 32
6147 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6148 client_secret:
6149 type: string
6150 pattern: /^[a-zA-Z0-9]$/
6151 maxLength: 32
6152 minLength: 32
6153 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6154 OAuthToken-password:
6155 allOf:
6156 - $ref: '#/components/schemas/OAuthClient'
6157 - type: object
6158 properties:
6159 grant_type:
6160 type: string
6161 enum:
6162 - password
6163 - refresh_token
6164 default: password
6165 username:
6166 $ref: '#/components/schemas/User/properties/username'
6167 password:
6168 $ref: '#/components/schemas/password'
6169 required:
6170 - client_id
6171 - client_secret
6172 - grant_type
6173 - username
6174 - password
6175 OAuthToken-refresh_token:
6176 allOf:
6177 - $ref: '#/components/schemas/OAuthClient'
6178 - type: object
6179 properties:
6180 grant_type:
6181 type: string
6182 enum:
6183 - password
6184 - refresh_token
6185 default: password
6186 refresh_token:
6187 type: string
6188 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6189 required:
6190 - client_id
6191 - client_secret
6192 - grant_type
6193 - refresh_token
6194
6001 VideoChannel: 6195 VideoChannel:
6002 properties: 6196 properties:
6003 # GET/POST/PUT properties 6197 # GET/POST/PUT properties