|
| 1 | +export const metadata = { |
| 2 | + title: 'Authentication', |
| 3 | + description: |
| 4 | + 'This page documents the authentication endpoints of the API.', |
| 5 | +} |
| 6 | + |
1 | 7 | # Authentication
|
2 | 8 |
|
3 |
| -## `GET /auth` |
| 9 | +## Trigger auth provider flow {{ tag: 'GET', label: '/auth' }} |
4 | 10 |
|
5 |
| -#### Description: |
| 11 | +<Row> |
| 12 | + <Col> |
6 | 13 |
|
7 |
| -Redirects the user to the authorization URI of the specified authentication provider. |
| 14 | + Redirects the user to the authorization URI of the specified authentication provider. (e.g., Google OAuth2 authorization page). |
8 | 15 |
|
9 |
| -#### Query Parameters: |
| 16 | + ### Optional Query Params |
10 | 17 |
|
11 |
| -- `providerId` `string`: The ID of the authentication provider. |
| 18 | + <Properties> |
| 19 | + <Property name="providerId" type="string"> |
| 20 | + The ID of the authentication provider. |
| 21 | + </Property> |
| 22 | + </Properties> |
12 | 23 |
|
13 |
| -#### Example Request (URL): |
| 24 | + </Col> |
14 | 25 |
|
15 |
| -``` |
16 |
| -GET /auth?providerId=google |
17 |
| -``` |
| 26 | + <Col sticky> |
18 | 27 |
|
19 |
| -#### Example Response (Redirect): |
| 28 | + <CodeGroup title="Request" tag="GET" label="/auth"> |
20 | 29 |
|
21 |
| -This will redirect the user to the authorization URI of the specified provider (e.g., Google OAuth2 authorization page). |
| 30 | + ```bash {{ title: 'cURL' }} |
| 31 | + curl -G http://localhost:7472/api/v1/auth \ |
| 32 | + -d providerId=google |
| 33 | + ``` |
| 34 | + </CodeGroup> |
22 | 35 |
|
23 |
| -```http |
24 |
| -HTTP/1.1 302 Found |
25 |
| -Location: https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=...&response_type=code&scope=... |
26 |
| -``` |
| 36 | + |
| 37 | + ```http {{ title: 'Response' }} |
| 38 | + HTTP/1.1 302 Found |
| 39 | + Location: https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=...&response_type=code&scope=... |
| 40 | + ``` |
27 | 41 |
|
28 |
| -## `GET /auth/callback2` |
| 42 | + </Col> |
| 43 | +</Row> |
29 | 44 |
|
30 |
| -#### Description: |
| 45 | +--- |
31 | 46 |
|
32 |
| -Callback endpoint for authentication providers after user authorization. It exchanges the authorization code or token |
33 |
| -for an access token. |
| 47 | +## Callback endpoint {{ tag: 'GET', label: '/auth/callback2' }} |
34 | 48 |
|
35 |
| -#### Query Parameters: |
| 49 | +<Row> |
| 50 | + <Col> |
36 | 51 |
|
37 |
| -- `state` `string`: The provider ID passed in the initial authentication request, used to identify the provider. |
| 52 | + Callback endpoint for authentication providers after user authorization. It exchanges the authorization code or token |
| 53 | + for an access token. |
38 | 54 |
|
39 |
| -#### Example Request (URL): |
| 55 | + ### Optional Query Params |
40 | 56 |
|
41 |
| -``` |
42 |
| -GET /auth/callback2?state=google&code=authorizationCodeHere |
43 |
| -``` |
| 57 | + <Properties> |
| 58 | + <Property name="state" type="string"> |
| 59 | + The provider ID passed in the initial authentication request, used to identify the provider. |
| 60 | + </Property> |
| 61 | + </Properties> |
44 | 62 |
|
45 |
| -#### Example Response (Redirect): |
| 63 | + </Col> |
46 | 64 |
|
47 |
| -Upon success, redirects to the login success page. |
| 65 | + <Col sticky> |
48 | 66 |
|
49 |
| -```http |
50 |
| -HTTP/1.1 302 Found |
51 |
| -Location: /loginsuccess?provider=google |
52 |
| -``` |
| 67 | + <CodeGroup title="Request" tag="GET" label="/auth/callback2"> |
53 | 68 |
|
54 |
| -#### Example Response (Error): |
| 69 | + ```bash {{ title: 'cURL' }} |
| 70 | + curl -G http://localhost:7472/api/v1/auth/callback2 \ |
| 71 | + -d state=google \ |
| 72 | + -d code=authorizationCodeHere |
| 73 | + ``` |
| 74 | + </CodeGroup> |
55 | 75 |
|
56 |
| -If the `state` parameter is invalid or missing, returns an error response. |
| 76 | + <CodeGroup title="Response" tag="GET" label="/auth/callback2"> |
57 | 77 |
|
58 |
| -```json |
59 |
| -{ |
60 |
| - "error": "Invalid provider id in state" |
61 |
| -} |
62 |
| -``` |
| 78 | + ```http {{ title: 'Success (Redirect)' }} |
| 79 | + HTTP/1.1 302 Found |
| 80 | + Location: https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=...&response_type=code&scope=... |
| 81 | + ``` |
63 | 82 |
|
64 |
| -If the authentication fails (e.g., invalid token exchange or an OAuth error), the response will be: |
| 83 | + ```json {{ title: 'Error (Invalid State)' }} |
| 84 | + { |
| 85 | + "error": "Invalid provider id in state" |
| 86 | + } |
| 87 | + ``` |
65 | 88 |
|
66 |
| -```json |
67 |
| -{ |
68 |
| - "error": "Authentication failed" |
69 |
| -} |
70 |
| -``` |
| 89 | + ```json {{ title: 'Error (Auth Failed)' }} |
| 90 | + { |
| 91 | + "error": "Authentication failed" |
| 92 | + } |
| 93 | + ``` |
| 94 | + |
| 95 | + </CodeGroup> |
| 96 | + </Col> |
| 97 | +</Row> |
0 commit comments