Skip to content

Commit 29992aa

Browse files
HasiniSamaHasiniSama
authored
Merge pull request #5212 from HasiniSama/org-user-api
Add Organization End User API to IS documentation and Add Organization Handle to Organization User API
2 parents 57fe2b9 + bdca793 commit 29992aa

File tree

12 files changed

+1380
-0
lines changed

12 files changed

+1380
-0
lines changed

‎en/asgardeo/docs/apis/restapis/user-organization.yaml

Lines changed: 333 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
openapi: 3.0.0
2+
info:
3+
version: "v1"
4+
title: 'Asgardeo - User Organization Management API Definition'
5+
description: |
6+
This document specifies an **User Organization Management RESTful API** for **Asgardeo**.
7+
8+
This API provides the capability to retrieve the resident organization of the authenticated user.
9+
license:
10+
name: Apache 2.0
11+
url: https://www.apache.org/licenses/LICENSE-2.0.html
12+
servers:
13+
- url: 'https://api.asgardeo.io/t/{root-organization-name}/api/users/v1/me/organizations'
14+
variables:
15+
root-organization-name:
16+
default: {root-organization-name}
17+
security:
18+
- OAuth2: []
19+
20+
tags:
21+
- name: me
22+
description: Operations for the authenticated user
23+
24+
paths:
25+
/:
26+
get:
27+
tags:
28+
- me
29+
summary:
30+
This API is used to search and retrieve child organizations which are authorized for the user.
31+
description:
32+
Retrieve authorized organizations which matches the defined search criteria, if any.
33+
parameters:
34+
- $ref: '#/components/parameters/filterQueryParam'
35+
- $ref: '#/components/parameters/limitQueryParam'
36+
- $ref: '#/components/parameters/afterQueryParam'
37+
- $ref: '#/components/parameters/beforeQueryParam'
38+
- $ref: '#/components/parameters/recursiveQueryParam'
39+
- $ref: '#/components/parameters/authorizedAppNameQueryParam'
40+
responses:
41+
'200':
42+
description: Successful response
43+
content:
44+
application/json:
45+
schema:
46+
$ref: '#/components/schemas/OrganizationsResponse'
47+
'400':
48+
$ref: '#/components/responses/BadRequest'
49+
'401':
50+
$ref: '#/components/responses/Unauthorized'
51+
'403':
52+
$ref: '#/components/responses/Forbidden'
53+
'500':
54+
$ref: '#/components/responses/ServerError'
55+
'501':
56+
$ref: '#/components/responses/NotImplemented'
57+
x-codeSamples:
58+
- lang: Curl
59+
source: |
60+
curl --location 'https://api.asgardeo.io/t/{root-organization-name}/api/users/v1/me/organizations' \
61+
-H 'Authorization: Bearer {access_token}' \
62+
-H 'Content-Type: application/json'
63+
/root:
64+
get:
65+
tags:
66+
- me
67+
summary: |
68+
Get the root organization of the authenticated user
69+
description: |
70+
This API provides the capability to retrieve the root organization of the authenticated user.
71+
72+
<b>Scope(Permission) required:</b> `internal_login`
73+
responses:
74+
'200':
75+
description: Successful Response
76+
content:
77+
application/json:
78+
schema:
79+
$ref: '#/components/schemas/RootOrganizationResponse'
80+
'401':
81+
$ref: '#/components/responses/Unauthorized'
82+
'403':
83+
$ref: '#/components/responses/Forbidden'
84+
'404':
85+
$ref: '#/components/responses/NotFound'
86+
'500':
87+
$ref: '#/components/responses/ServerError'
88+
x-codeSamples:
89+
- lang: Curl
90+
source: |
91+
curl --location 'https://api.asgardeo.io/t/{root-organization-name}/api/users/v1/me/organizations/root' \
92+
-H 'Authorization: Bearer {access_token}' \
93+
-H 'Content-Type: application/json'
94+
/root/descendants:
95+
get:
96+
tags:
97+
- me
98+
summary: |
99+
Get the descendant organizations of the authenticated user's resident organization
100+
description: |
101+
This API provides the capability to retrieve
102+
the descendant organizations of the authenticated user's resident organizations. The response includes
103+
the organization's id and name from the resident organization to the accessed child organization.
104+
105+
<b>Scope(Permission) required:</b> `internal_login`
106+
responses:
107+
'200':
108+
description: Successful Response
109+
content:
110+
application/json:
111+
schema:
112+
$ref: '#/components/schemas/RootDescendantsOrganizationResponse'
113+
'401':
114+
$ref: '#/components/responses/Unauthorized'
115+
'403':
116+
$ref: '#/components/responses/Forbidden'
117+
'404':
118+
$ref: '#/components/responses/NotFound'
119+
'500':
120+
$ref: '#/components/responses/ServerError'
121+
x-codeSamples:
122+
- lang: Curl
123+
source: |
124+
curl --location 'https://api.asgardeo.io/t/{root-organization-name}/api/users/v1/me/organizations/root/descendants' \
125+
-H 'Authorization: Bearer {access_token}' \
126+
-H 'Content-Type: application/json'
127+
128+
components:
129+
parameters:
130+
filterQueryParam:
131+
in: query
132+
name: filter
133+
required: false
134+
description:
135+
Condition to filter the retrieval of records.
136+
schema:
137+
type: string
138+
limitQueryParam:
139+
in: query
140+
name: limit
141+
required: false
142+
description:
143+
Maximum number of records to be returned. (Should be greater than 0)
144+
schema:
145+
type: integer
146+
format: int32
147+
minimum: 0
148+
beforeQueryParam:
149+
in: query
150+
name: before
151+
required: false
152+
description:
153+
Points to the previous range of data that can be retrieved.
154+
schema:
155+
type: string
156+
afterQueryParam:
157+
in: query
158+
name: after
159+
required: false
160+
description:
161+
Points to the next range of data to be returned.
162+
schema:
163+
type: string
164+
recursiveQueryParam:
165+
in: query
166+
name: recursive
167+
required: false
168+
description:
169+
Determines whether a recursive search should happen.
170+
schema:
171+
type: boolean
172+
default: false
173+
authorizedAppNameQueryParam:
174+
in: query
175+
name: authorizedAppName
176+
required: false
177+
description:
178+
Retrieves the organizations that are authorized for the user through the role bound to the application.
179+
schema:
180+
type: string
181+
schemas:
182+
RootOrganizationResponse:
183+
type: object
184+
required:
185+
- id
186+
- name
187+
properties:
188+
id:
189+
type: string
190+
example: '77084a9d-113f-8281-a0d3-efe34b083213'
191+
name:
192+
type: string
193+
example: 'ABC Builders'
194+
195+
OrganizationsResponse:
196+
type: object
197+
properties:
198+
links:
199+
type: array
200+
items:
201+
$ref: '#/components/schemas/Link'
202+
example:
203+
[
204+
{
205+
"href": "/t/{root-organization-name}/api/users/v1/me/organizations?limit=10&filter=name+co+der&next=MjAyMS0xMi0yMSAwNToxODozMS4wMDQzNDg=",
206+
"rel": "next",
207+
}, {
208+
"href": "/t/{root-organization-name}/api/users/v1/me/organizations?limit=10&filter=name+co+der&before=MjAyMS0xMi0yMSAwNToxODozMS4wMDQzNDg=",
209+
"rel": "previous",
210+
}
211+
]
212+
organizations:
213+
type: array
214+
items:
215+
$ref: '#/components/schemas/Organization'
216+
Link:
217+
type: object
218+
properties:
219+
href:
220+
type: string
221+
format: uri
222+
description: Endpoint that will return the next or previous page of data.
223+
rel:
224+
type: string
225+
description: Describes whether the provided link is to access the next or previous page of data.
226+
readOnly: true
227+
Organization:
228+
type: object
229+
required:
230+
- id
231+
- name
232+
- status
233+
- ref
234+
properties:
235+
id:
236+
type: string
237+
example: 'b4526d91-a8bf-43d2-8b14-c548cf73065b'
238+
name:
239+
type: string
240+
example: 'ABC Builders'
241+
status:
242+
type: string
243+
enum: [ ACTIVE, DISABLED ]
244+
example: ACTIVE
245+
ref:
246+
type: string
247+
example: '/t/{root-organization-name}/api/server/v1/organizations/b4526d91-a8bf-43d2-8b14-c548cf73065b'
248+
249+
BasicOrganizationObject:
250+
type: object
251+
required:
252+
- id
253+
- name
254+
properties:
255+
id:
256+
type: string
257+
example: '77084a9d-113f-8281-a0d3-efe34b083213'
258+
name:
259+
type: string
260+
example: 'ABC Builders'
261+
262+
RootDescendantsOrganizationResponse:
263+
type: array
264+
items:
265+
$ref: '#/components/schemas/BasicOrganizationObject'
266+
267+
Error:
268+
type: object
269+
required:
270+
- code
271+
- message
272+
properties:
273+
code:
274+
type: string
275+
example: UOM-00000
276+
description: An error code.
277+
message:
278+
type: string
279+
example: Some Error Message
280+
description: An error message.
281+
description:
282+
type: string
283+
example: Some Error Description
284+
description: An error description.
285+
traceId:
286+
type: string
287+
example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047
288+
description: An error trace identifier.
289+
290+
#--------------------------------------------------------
291+
# Descriptions of error responses.
292+
#--------------------------------------------------------
293+
responses:
294+
BadRequest:
295+
description: Invalid input in the request.
296+
content:
297+
'application/json':
298+
schema:
299+
$ref: '#/components/schemas/Error'
300+
NotFound:
301+
description: Resource is not found.
302+
content:
303+
'application/json':
304+
schema:
305+
$ref: '#/components/schemas/Error'
306+
Unauthorized:
307+
description: Authentication information is missing or invalid.
308+
Forbidden:
309+
description: Access forbidden.
310+
ServerError:
311+
description: Internal server error.
312+
content:
313+
'application/json':
314+
schema:
315+
$ref: '#/components/schemas/Error'
316+
NotImplemented:
317+
description: Not Implemented.
318+
content:
319+
'application/json':
320+
schema:
321+
$ref: '#/components/schemas/Error'
322+
323+
#-----------------------------------------------------
324+
# Applicable authentication mechanisms.
325+
#-----------------------------------------------------
326+
securitySchemes:
327+
OAuth2:
328+
type: oauth2
329+
flows:
330+
authorizationCode:
331+
authorizationUrl: 'https://api.asgardeo.io/t/{root-organization-name}/oauth2/authorize'
332+
tokenUrl: 'https://api.asgardeo.io/t/{root-organization-name}/oauth2/token'
333+
scopes: {}

‎en/asgardeo/docs/apis/user-organization-api.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
template: templates/redoc.html
3+
---
4+
5+
<redoc spec-url="../../apis/restapis/user-organization.yaml" theme='{{redoc_theme}}'></redoc>

‎en/asgardeo/mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -564,6 +564,7 @@ nav:
564564
- User account associations API: apis/association-management-by-user.md
565565
- Export user information API: apis/export-user-info.md
566566
- Identity Verification: apis/user-identity-verification.md
567+
- Organization Me API: apis/user-organization-api.md
567568
- References:
568569
- References - Overview: references/index.md
569570
- Operational policies: references/operational-policies.md

0 commit comments

Comments
 (0)