· 7 years ago · Mar 21, 2018, 09:12 AM
1openapi: 3.0.0
2info:
3 version: '3.0'
4 title: Vizibl API
5 description: Vizibl REST API
6 termsOfService: 'https://api.vizibl.co/terms'
7 contact:
8 name: Vizibl API Support
9 email: developers@oldstlabs.co
10 x-logo:
11 url: /assets/img/logo.png
12 backgroundColor: null
13servers:
14 - url: 'https://{subdomain}.vizibl.co/{version}'
15 description: Production API
16 variables:
17 subdomain:
18 enum:
19 - dev-api
20 - qa-api
21 - stage-api
22 - preprod-api
23 - sandbox-api
24 default: api
25 version:
26 enum:
27 - v1
28 - v2
29 - v3
30 default: v3
31paths:
32 /oauth/authorization:
33 get:
34 summary: Authenticate an end user.
35 description: |
36 See OAuth 2.0 Authorization Endpoint](http://tools.ietf.org/html/rfc6749#section-3.1)
37 operationId: authorize
38 parameters:
39 - $ref: '#/components/parameters/clientId'
40 - $ref: '#/components/parameters/scopes'
41 - $ref: '#/components/parameters/state'
42 - $ref: '#/components/parameters/redirectUri'
43 - $ref: '#/components/parameters/responseType'
44 responses:
45 '302':
46 description: Successful or erroneous authentication response.
47 /oauth/token:
48 post:
49 summary: Obtain an authentication token.
50 description: |
51 TODO
52 operationId: token
53 parameters:
54 - name: Authorization
55 in: header
56 description: HTTP Basic authorization header.
57 required: false
58 schema:
59 type: string
60 responses:
61 '200':
62 $ref: '#/components/responses/Token'
63 '400':
64 $ref: '#/components/responses/OAuth2Error'
65 '401':
66 $ref: '#/components/responses/UNAUTHORIZED'
67 /users/me:
68 get:
69 summary: Fetch a user object using token
70 description: This API will return the user object that belongs to the provided authentication token.
71 operationId: getAuthenticatedUser
72 parameters:
73 - $ref: '#/components/parameters/withemailParam'
74 - $ref: '#/components/parameters/withpermittedcompaniesParam'
75 security:
76 - OAuth2:
77 - 'read:users'
78 - bearerAuth: []
79 responses:
80 '200':
81 description: OK
82 '401':
83 $ref: '#/components/responses/UNAUTHORIZED'
84 '403':
85 $ref: '#/components/responses/FORBIDDEN'
86components:
87 schemas:
88 Error:
89 properties:
90 code:
91 type: string
92 message:
93 type: string
94 required:
95 - code
96 - message
97 Token:
98 description: Successful token response
99 required:
100 - token_type
101 properties:
102 token_type:
103 type: string
104 access_token:
105 description: The access token issued by the authorization server.
106 type: string
107 id_token:
108 description: ID Token value associated with the authenticated session.
109 type: string
110 refresh_token:
111 description: 'The refresh token issued to the client, if any.'
112 type: string
113 expires_in:
114 description: The lifetime in seconds of the access token.
115 type: integer
116 format: int32
117 expires_at:
118 description: The time the access token will expire in seconds since epoch.
119 type: integer
120 format: int64
121 scope:
122 description: The scope of the granted tokens.
123 type: string
124 OAuth2Error:
125 description: 'Error Response defined as in Section 5.2 of OAuth 2.0 [RFC6749].'
126 required:
127 - error
128 properties:
129 error:
130 type: string
131 error_description:
132 type: string
133 parameters:
134 withemailParam:
135 in: query
136 name: with_email_details
137 description: Return the user object with their email details.
138 schema:
139 type: string
140 required: false
141 withpermittedcompaniesParam:
142 in: query
143 name: with_permitted_companies
144 description: Return the user object with the list of permitted Company objects that the user has permissons to access.
145 schema:
146 type: string
147 required: false
148 clientId:
149 in: query
150 name: client_id
151 description: Vizibl Client ID
152 schema:
153 type: string
154 required: true
155 scopes:
156 in: query
157 name: scopes
158 description: Token allowed permission scopes
159 schema:
160 type: string
161 required: true
162 state:
163 in: query
164 name: state
165 description: |
166 An opaque string that will be passed back to the redirect URL and therefore can be used to communicate client side state and prevent CSRF attacks.
167 schema:
168 type: string
169 required: true
170 redirectUri:
171 in: query
172 name: redirect_uri
173 description: |
174 The location to redirect to after (un)successful authentication.
175 schema:
176 type: string
177 required: true
178 responseType:
179 in: query
180 name: response_type
181 description: |
182 The OIDC response type to use for this authentication flow. Valid choices are `code` and `token`.
183 schema:
184 type: string
185 required: true
186 responses:
187 BAD_REQUEST:
188 description: Bad Request
189 content:
190 application/json:
191 schema:
192 $ref: '#/components/schemas/Error'
193 UNAUTHORIZED:
194 description: Unauthorized
195 content:
196 application/json:
197 schema:
198 $ref: '#/components/schemas/Error'
199 FORBIDDEN:
200 description: Forbidden
201 content:
202 application/json:
203 schema:
204 $ref: '#/components/schemas/Error'
205 NOT_FOUND:
206 description: Not Found
207 content:
208 application/json:
209 schema:
210 $ref: '#/components/schemas/Error'
211 PRE_CONDITION_FAILED:
212 description: Pre Condition Failed
213 content:
214 application/json:
215 schema:
216 $ref: '#/components/schemas/Error'
217 CANNOT_ACCESS_COMPANY:
218 description: Cannot Access Company
219 content:
220 application/json:
221 schema:
222 $ref: '#/components/schemas/Error'
223 Token:
224 description: Token Response
225 content:
226 application/x-www-form-urlencoded:
227 schema:
228 $ref: '#/components/schemas/Error'
229 application/json:
230 schema:
231 $ref: '#/components/schemas/Error'
232 OAuth2Error:
233 description: OAuth 2.0 error response
234 content:
235 application/x-www-form-urlencoded:
236 schema:
237 $ref: '#/components/schemas/Oauth2Error'
238 application/json:
239 schema:
240 $ref: '#/components/schemas/Oauth2Error'
241 securitySchemes:
242 OAuth2:
243 type: oauth2
244 description: User authentication.
245 flows:
246 authorizationCode:
247 authorizationUrl: oauth/authorization
248 tokenUrl: oauth/token
249 scopes:
250 'read:users': Read users
251 JWT:
252 description: JWT authentication.
253 type: oauth2
254 flows:
255 clientCredentials:
256 tokenUrl: oauth/token
257 refreshUrl: oauth/token
258 bearerAuth:
259 type: http
260 scheme: bearer
261 bearerFormat: JWT