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