Created
September 28, 2023 09:42
-
-
Save xeptore/2af2f76744691bea457698c22c96e8e8 to your computer and use it in GitHub Desktop.
openapi.yml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
components: | |
securitySchemes: | |
bearerToken: | |
bearerFormat: JWT | |
scheme: bearer | |
type: http | |
cookieToken: | |
in: cookie | |
name: __Host-session_id | |
type: apiKey | |
info: | |
contact: | |
email: [email protected] | |
name: Contact Name | |
url: https://falomen.app | |
description: | | |
[Changelog](/docs/changelogs/v4.0.0) | |
title: Falomen API | |
version: v4.0.0 | |
openapi: 3.1.0 | |
paths: | |
/api/v1/admin/auth/signin: | |
post: | |
deprecated: false | |
operationId: signinAdmin | |
parameters: | |
- deprecated: false | |
description: | | |
If provided, will be used as the target language to translate messages into according to [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt). | |
Read more at: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language>. | |
If the specified language is not supported, it will fallback to `en-US` (American English). | |
Language of the response will be set in the `content-language` header. See: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language> | |
examples: | |
ChineseWithFallback: | |
summary: Chinese with Fallback to English | |
value: cn,en-US | |
English: | |
summary: American English | |
value: en-US | |
NotSupported: | |
summary: Not-supported Language | |
value: xyz | |
in: header | |
name: accept-language | |
required: false | |
schema: | |
type: string | |
requestBody: | |
content: | |
application/json: | |
examples: | |
ValidEmail: | |
summary: Valid Signin with Email Credentials | |
value: | |
emailOrUsername: [email protected] | |
googleRecaptchaToken: 03AFcWeA7eYVYAPswBUN1ldPyLOpRIq6qmzRIVB22rm6XD65FHG5y7MD06SUEhaXR-iuYPT5Lyae-CE9WfaeazzM8TRNBTWFVVnU7iTGX2E3Zyuoh6Hru_yIz3sj6kiv9hzCdVyZG5xwwJBdOJUkh4w5tYqIQ0lcDUWmQFYfidYqhnpJd-tuG93Qo904Anpaq_FD1jIDclpsTrWW18nswF91_b7OhHeuQ9_4v0u1UammAaufCNZkgGVXtukWSbcl1pvfIiyBarDsPninY_CQBS35VweBGTFWgKbbU1LCmouZBucvs1cfooGNOo1mrwVMm5SbIm1MHEBdpWTM9BE8UQGgelZFe7PxibvZas6n_3C0Pj7wj6M9o69Rz6fgz0mTN-bJLJvj5eHM3AMuiev1jOyyd88EHlMfbUiEaF83DAckvEFmil8kqTbl79Ocv8bQ41_Wiof8l8ZH_2KT-6TkucUBfejSD_Lt09zBJIbkBqNeBVD4BxhXDssc4qBnl2S22ZMrueLabX7butAFqKyYs3R3TPwMO6g8up3E_HF4dE-FiZCmzRHlVya6ADiseBN3N8ZbxGzFYng_4m | |
password: 1234567890abcdefrghiklmnopqrstuvwxyz | |
ValidUsername: | |
summary: Valid Signin with Username Credentials | |
value: | |
emailOrUsername: john.doe | |
googleRecaptchaToken: 03AFcWeA7eYVYAPswBUN1ldPyLOpRIq6qmzRIVB22rm6XD65FHG5y7MD06SUEhaXR-iuYPT5Lyae-CE9WfaeazzM8TRNBTWFVVnU7iTGX2E3Zyuoh6Hru_yIz3sj6kiv9hzCdVyZG5xwwJBdOJUkh4w5tYqIQ0lcDUWmQFYfidYqhnpJd-tuG93Qo904Anpaq_FD1jIDclpsTrWW18nswF91_b7OhHeuQ9_4v0u1UammAaufCNZkgGVXtukWSbcl1pvfIiyBarDsPninY_CQBS35VweBGTFWgKbbU1LCmouZBucvs1cfooGNOo1mrwVMm5SbIm1MHEBdpWTM9BE8UQGgelZFe7PxibvZas6n_3C0Pj7wj6M9o69Rz6fgz0mTN-bJLJvj5eHM3AMuiev1jOyyd88EHlMfbUiEaF83DAckvEFmil8kqTbl79Ocv8bQ41_Wiof8l8ZH_2KT-6TkucUBfejSD_Lt09zBJIbkBqNeBVD4BxhXDssc4qBnl2S22ZMrueLabX7butAFqKyYs3R3TPwMO6g8up3E_HF4dE-FiZCmzRHlVya6ADiseBN3N8ZbxGzFYng_4m | |
password: 1234567890abcdefrghiklmnopqrstuvwxyz | |
schema: | |
properties: | |
emailOrUsername: | |
maxLength: 256 | |
minLength: 4 | |
title: Email or Username | |
type: string | |
googleRecaptchaToken: | |
maxLength: 1000 | |
minLength: 500 | |
title: Google reCaptcha Token | |
type: string | |
password: | |
maxLength: 128 | |
minLength: 10 | |
title: Password | |
type: string | |
required: | |
- emailOrUsername | |
- password | |
- googleRecaptchaToken | |
type: object | |
unevaluatedProperties: false | |
responses: | |
"201": | |
content: | |
application/json: | |
examples: | |
Successful: | |
summary: Successful Signin | |
value: | |
bearerToken: eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTU5ODIwMTIsImlhdCI6MTY5NTM3NzIxMiwiaXNzIjoiYXV0aC5mYWxvbWVuIiwianRpIjoiUWtoNVNwX2tfaVZDai05bFhrb1J3dExGX1pjRVZadXpUNnEweU1VdFl2Qk0tdkd0WjJFaHM0TFoyR0dHb1A3TGltNFY4aUh3NklWOVQ0ci1QalRobGVjQ0FfY1ZBRkwxd2tZUjQ0amFWZkViQzNlb3U3d0ExNzdaNUR3eXE2WFAiLCJzZXNzaW9uX2lkIjoiMlFicWpETnVhNnFILXdiVFJzYkR6QzcyQTZVTWRyR1l2SktZZHVzMjVhbVdZdVhPWGl2cTlxOHJQSDdCbGd6dUtkQUs2WVNMak5iWEM3ZHZ1T1hXOFh0aGxtNlp2SkdHN1dQUiIsInN1YiI6Im9KWW1Bb3ZhV09mdmNzcGFWTVIyIn0.P3QWD_qiL_ixCQRi8iQ_dkEPuneTPlzlxirVoBjCOMJf_hfOOydy6slCNEU_ylEueL3waiusQsmQYflCR6jnDA | |
expiresAt: "2023-09-29T10:06:52Z" | |
refreshToken: ZTgltjs27StJr9bRfpK-N52_OccwC8q3Rm7pFLwyoUmYDjxGN6l8nVFdN7f-x0swiUsLIC6nqwBq-KH6o7TTcattihQV4u-3vtluUIgv6oNWCXEdQKNdbqwjte4Jy5iBUkAV4I11XCPuEo0CjvV5h0H6kY5snEwN2wHYHZ4VXVlessEjkasN55-NBhTBYraWA6hLpc-2NHpFNyEDn3br8bWOiq4GrkHKdWKUtB-ZENdU9HKf9Xskpva_XpQBWBoXuR7oA3llQ1Lp0AiQ9eHCD7QukZFPxCL1qmDWf2h9n24RiYvbn5L8jHNZc5YLC1cixry4TR7diOIqp0aDq5ucuIThoO4Sfispg6HXFG6_viaoMRmLY2_Epr3JQldg3eXDk5HJ2a-XeWlRCJZSU_R-e4GvG5C1Nhn2dWLLkHrOSKxxCBENJ1BZiVgpMTAzIOXBTXCwPsVDXO7piTKU6sf9Qs-tJ3i2SpqHvDwFc37iMqyP_Wryfe46uVV4EdewB5otZ9vBmQupS7d0QAu5GLu9G-VAlk9B9HoZ1_LkyDoSSd0Kv_s4J86VNszL-CtKTzxVeD4UNtJqbbwHQbxSpFocZYKiiY3GQaLVXgWcTAwsyBE66uwDra7Fqf8cqDy5DEeeYSteb8G7TghoJvMjtLDbszWzmCkgRcYcUyn4cuTABu9g-f4Ntn-tign7ck8zpPjeGh6AlVhLoGjDwkK8sfAPFHtWuxLLHRyaf7tStZwmEFpST5zP3FIq6Tf-4gFnPzfqSk-vP1qBhy2ThDVjidinpYV2C7-CBhIOEzpXr7lu3xcLhgu_Y4pSH3BLPwSDyYlIZxWVW1xlnKknAvEG8rwcENSr3Bw0i1HGjYmYv2lSlqo4rqChLY34KnQO7nXiURT2kXp0WQSiDB_Bfujfjjh7UI9_g51l1-KGMpho_bt1fLp8B-_vX8YoDPDZ8vEDcOIDLQGSUQU0tEBpSGJtzlFN95hpxwfm25J2ZRNUJSeBnCFp5gjefien0OGLuz_yFv37 | |
refreshTokenExpiresAt: "2023-10-20T10:06:52Z" | |
schema: | |
properties: | |
bearerToken: | |
description: | | |
Bearer token in JWT format that must be provided in the `authorization` request header. | |
title: Bearer Token | |
type: string | |
expiresAt: | |
description: | | |
Bearer token expiration date time in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. The token should not be used after expiration. Doing so, will result in the session termination. | |
maxLength: 20 | |
minLength: 20 | |
title: Bearer Token Expiration Time | |
type: string | |
refreshToken: | |
description: | | |
Refresh token that must only be used with the respective API after expiration of the Bearer Token to receive a new token falimiy. | |
title: Refresh Token | |
type: string | |
refreshTokenExpiresAt: | |
description: | | |
Refresh token expiration date time in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. If the token is not used to receive a new token set before expiration, the session will be terminated. | |
maxLength: 20 | |
minLength: 20 | |
title: Refresh Token Expiration Time | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Signin is successfull, and new session is created. | |
headers: | |
set-cookie: | |
description: | | |
Sets cookie token. | |
examples: | |
Example: | |
summary: Cookie Token | |
value: __Host-session_id=JG9nXLC01esyq4vTZUcJ4xM00RMd8HU0WjsVEhIR-fSqz0ubWo9ND9ygLHCqT2Q5r9TKzqh8VgPl9Xx6CfQ5bhbxn_pbMF7OBSMnXR1oWy0yME5rNLs8x0BKEqHavapf; Path=/; Expires=Mon, 02 Oct 2023 02:14:20 GMT; HttpOnly; Secure; SameSite=Strict | |
required: true | |
schema: | |
type: string | |
"400": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Invalid request payload. | |
schema: | |
properties: | |
error: | |
description: | | |
Error message translated based on request language header. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: | | |
Request body is invalid. Make sure request body is compatible with the validation rules defined the request body section. | |
"401": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Incorrect credentials. | |
schema: | |
properties: | |
error: | |
description: | | |
Error message translated based on request language header. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: | | |
Invalid credentials. Either email/username and password are incorrect, or Google reCaptcha token is not valid. | |
"406": | |
content: | |
application/json: | |
examples: | |
InvalidAcceptHeader: | |
summary: Invalid Accept Header | |
value: | |
error: expected the value "application/json" for the accept request header is expected | |
InvalidContentTypeHeader: | |
summary: Invalid ContentType Header | |
value: | |
error: expected the value "application/json" for the content-type request header | |
MultipleAcceptHeaders: | |
summary: Multiple Accept Headers | |
value: | |
error: exactly 1 value must be set for the accept request header | |
MultipleContentTypeHeaders: | |
summary: Multiple ContentType Headers | |
value: | |
error: exactly 1 value must be set for the content-type request header is expected | |
schema: | |
properties: | |
error: | |
description: | | |
Error message is not translated as it is not expected that the invalid request body is caused by the end-user, so as the response message will be. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Request headers are not accepted. | |
"500": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Internal server error occurred. Please try again later, and inform support if the error persists. | |
schema: | |
properties: | |
error: | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Internal error occurred. The error might be retryable if the respective header exists in the response. | |
headers: | |
falomen-should-retry: | |
deprecated: false | |
description: | | |
Optional header indicating whether the request should be retried by the client. It always have the value of `true` if present, i.e., only checking whether the header is present in the response body would suffice. | |
examples: | |
ShouldRetry: | |
summary: Should Retry Request | |
value: "true" | |
required: false | |
schema: | |
const: "true" | |
type: string | |
summary: Signin Admin | |
tags: | |
- Authentication | |
- Admin | |
/api/v1/auth/refresh: | |
post: | |
deprecated: false | |
operationId: refreshToken | |
parameters: | |
- deprecated: false | |
description: | | |
If provided, will be used as the target language to translate messages into according to [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt). | |
Read more at: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language>. | |
If the specified language is not supported, it will fallback to `en-US` (American English). | |
Language of the response will be set in the `content-language` header. See: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language> | |
examples: | |
ChineseWithFallback: | |
summary: Chinese with Fallback to English | |
value: cn,en-US | |
English: | |
summary: American English | |
value: en-US | |
NotSupported: | |
summary: Not-supported Language | |
value: xyz | |
in: header | |
name: accept-language | |
required: false | |
schema: | |
type: string | |
requestBody: | |
content: | |
application/json: | |
examples: | |
ValidBody: | |
summary: Valid Form | |
value: | |
refreshToken: ZTgltjs27StJr9bRfpK-N52_OccwC8q3Rm7pFLwyoUmYDjxGN6l8nVFdN7f-x0swiUsLIC6nqwBq-KH6o7TTcattihQV4u-3vtluUIgv6oNWCXEdQKNdbqwjte4Jy5iBUkAV4I11XCPuEo0CjvV5h0H6kY5snEwN2wHYHZ4VXVlessEjkasN55-NBhTBYraWA6hLpc-2NHpFNyEDn3br8bWOiq4GrkHKdWKUtB-ZENdU9HKf9Xskpva_XpQBWBoXuR7oA3llQ1Lp0AiQ9eHCD7QukZFPxCL1qmDWf2h9n24RiYvbn5L8jHNZc5YLC1cixry4TR7diOIqp0aDq5ucuIThoO4Sfispg6HXFG6_viaoMRmLY2_Epr3JQldg3eXDk5HJ2a-XeWlRCJZSU_R-e4GvG5C1Nhn2dWLLkHrOSKxxCBENJ1BZiVgpMTAzIOXBTXCwPsVDXO7piTKU6sf9Qs-tJ3i2SpqHvDwFc37iMqyP_Wryfe46uVV4EdewB5otZ9vBmQupS7d0QAu5GLu9G-VAlk9B9HoZ1_LkyDoSSd0Kv_s4J86VNszL-CtKTzxVeD4UNtJqbbwHQbxSpFocZYKiiY3GQaLVXgWcTAwsyBE66uwDra7Fqf8cqDy5DEeeYSteb8G7TghoJvMjtLDbszWzmCkgRcYcUyn4cuTABu9g-f4Ntn-tign7ck8zpPjeGh6AlVhLoGjDwkK8sfAPFHtWuxLLHRyaf7tStZwmEFpST5zP3FIq6Tf-4gFnPzfqSk-vP1qBhy2ThDVjidinpYV2C7-CBhIOEzpXr7lu3xcLhgu_Y4pSH3BLPwSDyYlIZxWVW1xlnKknAvEG8rwcENSr3Bw0i1HGjYmYv2lSlqo4rqChLY34KnQO7nXiURT2kXp0WQSiDB_Bfujfjjh7UI9_g51l1-KGMpho_bt1fLp8B-_vX8YoDPDZ8vEDcOIDLQGSUQU0tEBpSGJtzlFN95hpxwfm25J2ZRNUJSeBnCFp5gjefien0OGLuz_yFv37 | |
refreshTokenExpiresAt: "2023-10-20T10:06:52Z" | |
schema: | |
properties: | |
refreshToken: | |
maxLength: 1024 | |
minLength: 1024 | |
title: Refresh Token | |
type: string | |
refreshTokenExpiresAt: | |
description: | | |
Refresh token expiration date time in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. It's much easier to send what you received from the signin response as it was. | |
maxLength: 20 | |
minLength: 20 | |
title: Refresh Token Expires At | |
type: string | |
required: | |
- refreshToken | |
- refreshTokenExpiresAt | |
type: object | |
unevaluatedProperties: false | |
responses: | |
"201": | |
content: | |
application/json: | |
examples: | |
Successful: | |
summary: Successful Refresh Token | |
value: | |
bearerToken: eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTU5ODIwMTIsImlhdCI6MTY5NTM3NzIxMiwiaXNzIjoiYXV0aC5mYWxvbWVuIiwianRpIjoiUWtoNVNwX2tfaVZDai05bFhrb1J3dExGX1pjRVZadXpUNnEweU1VdFl2Qk0tdkd0WjJFaHM0TFoyR0dHb1A3TGltNFY4aUh3NklWOVQ0ci1QalRobGVjQ0FfY1ZBRkwxd2tZUjQ0amFWZkViQzNlb3U3d0ExNzdaNUR3eXE2WFAiLCJzZXNzaW9uX2lkIjoiMlFicWpETnVhNnFILXdiVFJzYkR6QzcyQTZVTWRyR1l2SktZZHVzMjVhbVdZdVhPWGl2cTlxOHJQSDdCbGd6dUtkQUs2WVNMak5iWEM3ZHZ1T1hXOFh0aGxtNlp2SkdHN1dQUiIsInN1YiI6Im9KWW1Bb3ZhV09mdmNzcGFWTVIyIn0.P3QWD_qiL_ixCQRi8iQ_dkEPuneTPlzlxirVoBjCOMJf_hfOOydy6slCNEU_ylEueL3waiusQsmQYflCR6jnDA | |
expiresAt: "2023-09-29T10:06:52Z" | |
refreshToken: ZTgltjs27StJr9bRfpK-N52_OccwC8q3Rm7pFLwyoUmYDjxGN6l8nVFdN7f-x0swiUsLIC6nqwBq-KH6o7TTcattihQV4u-3vtluUIgv6oNWCXEdQKNdbqwjte4Jy5iBUkAV4I11XCPuEo0CjvV5h0H6kY5snEwN2wHYHZ4VXVlessEjkasN55-NBhTBYraWA6hLpc-2NHpFNyEDn3br8bWOiq4GrkHKdWKUtB-ZENdU9HKf9Xskpva_XpQBWBoXuR7oA3llQ1Lp0AiQ9eHCD7QukZFPxCL1qmDWf2h9n24RiYvbn5L8jHNZc5YLC1cixry4TR7diOIqp0aDq5ucuIThoO4Sfispg6HXFG6_viaoMRmLY2_Epr3JQldg3eXDk5HJ2a-XeWlRCJZSU_R-e4GvG5C1Nhn2dWLLkHrOSKxxCBENJ1BZiVgpMTAzIOXBTXCwPsVDXO7piTKU6sf9Qs-tJ3i2SpqHvDwFc37iMqyP_Wryfe46uVV4EdewB5otZ9vBmQupS7d0QAu5GLu9G-VAlk9B9HoZ1_LkyDoSSd0Kv_s4J86VNszL-CtKTzxVeD4UNtJqbbwHQbxSpFocZYKiiY3GQaLVXgWcTAwsyBE66uwDra7Fqf8cqDy5DEeeYSteb8G7TghoJvMjtLDbszWzmCkgRcYcUyn4cuTABu9g-f4Ntn-tign7ck8zpPjeGh6AlVhLoGjDwkK8sfAPFHtWuxLLHRyaf7tStZwmEFpST5zP3FIq6Tf-4gFnPzfqSk-vP1qBhy2ThDVjidinpYV2C7-CBhIOEzpXr7lu3xcLhgu_Y4pSH3BLPwSDyYlIZxWVW1xlnKknAvEG8rwcENSr3Bw0i1HGjYmYv2lSlqo4rqChLY34KnQO7nXiURT2kXp0WQSiDB_Bfujfjjh7UI9_g51l1-KGMpho_bt1fLp8B-_vX8YoDPDZ8vEDcOIDLQGSUQU0tEBpSGJtzlFN95hpxwfm25J2ZRNUJSeBnCFp5gjefien0OGLuz_yFv379M1XDB1XFQJIkBhoe2isw4o3Ynfe8Cqg0rK483w4lj0l1C6RLneFdElOPTOusoR_a1lEgmaKjdtLaFEmmJ40c38bBy2Rj6FU9fE7duIfh0_bcoAVuP6ciotW-uo3SRv894zis3odrc2gFA19lAo4YYQ24eHxSowriLnYZEfxjvvZPSt-DGAhWx8S9j1XF6V0GOggMRqq49Oy1RRAQesz6ul_wJ-hDeTBgk3X0NpLs63jPmFBheQzsrEYzeFwV91fIkkcwwxhUmQPib0wNeYD4gzI2yg1iGC8G5f348SotHS8wvq-4Bd5LDwumX08yp0TFyUiz4MhVngQ9hcZq2DWkQowgn5K-ltpyFnObAHausNzrJ6QZha6ykB-Hmt3FB6_aC5TqpM8DcQNo6keprF30cYqlKVwDf4OM7E-D7wDJw20S-_SMhuvptvTrQ3azumAwv6Zd6uzQqRAYDVKhsAuDUwCeJhoBBmQPiiPcgPf50UIvS67ptC6P6bQSsKJNjOdTdoviefiQrHENLDtJrQpUxSNZfQx-9s89C7Ai6-FvoHGtKvytAMvvvr3_TlZCNBXoeHKmyAnurOiAFBqcsl6kd0cTC8x7r9LOcifBVMK4xkaljj-TQrlfVGTrBBN3KzhhtCqHS_oWbBO7jSGQIqB_Z7FVHDad2sVuaLwGkAbKoGSEANm5K-R3iKcmmtO72dAphccE0VZoYBWXHC8q4CnvG_aJcPOC6i-LNf9Ty68LiE4Q8jsx4flkM0Q4PXesx_Jl9rg5qRc4CWSyPBQ3G5OiE4AknuUCy11SC8BsHH2-DGBPLUUfKAFJmfbj3WVP7NQK9BKdhf1zSXao_mGYFTfa_fSuNeQ53KYJD8k7v80ydfFZmOgm4U6hgBxPLPTGRHyVOaQ7iTxzxqvi1VnUVRWL0VAyoHH_WJ0SYTXhH6Lrm1qnr8XXRimJlaumsmpManFyEuZnl9vkt3r9aqHBZUQKVfG3BWVTnpDrYRV5-MsIgayqbTT4LcCj_Zajdbp2IAf | |
refreshTokenExpiresAt: "2023-10-20T10:06:52Z" | |
schema: | |
properties: | |
bearerToken: | |
description: | | |
Bearer token in JWT format that must be provided in the `authorization` request header. | |
title: Bearer Token | |
type: string | |
expiresAt: | |
description: | | |
Bearer token expiration date time in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. The token should not be used after expiration. Doing so, will result in the session termination. | |
maxLength: 20 | |
minLength: 20 | |
title: Bearer Token Expiration Time | |
type: string | |
refreshToken: | |
description: | | |
Refresh token that must only be used with the respective API after expiration of the Bearer Token to receive a new token falimiy. | |
title: Refresh Token | |
type: string | |
refreshTokenExpiresAt: | |
description: | | |
Refresh token expiration date time in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. If the token is not used to receive a new token set before expiration, the session will be terminated. | |
maxLength: 20 | |
minLength: 20 | |
title: Refresh Token Expiration Time | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Refresh is successfull, and new session token is created. | |
headers: | |
set-cookie: | |
description: | | |
Sets cookie token. | |
examples: | |
Example: | |
summary: Cookie Token | |
value: __Host-session_id=JG9nXLC01esyq4vTZUcJ4xM00RMd8HU0WjsVEhIR-fSqz0ubWo9ND9ygLHCqT2Q5r9TKzqh8VgPl9Xx6CfQ5bhbxn_pbMF7OBSMnXR1oWy0yME5rNLs8x0BKEqHavapf; Path=/; Expires=Mon, 02 Oct 2023 02:14:20 GMT; HttpOnly; Secure; SameSite=Strict | |
required: true | |
schema: | |
type: string | |
"400": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Invalid request payload. | |
schema: | |
properties: | |
error: | |
description: | | |
Error message translated based on request language header. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: | | |
Request body is invalid. Make sure request body is compatible with the validation rules defined the request body section. | |
"401": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Incorrect credentials. | |
schema: | |
properties: | |
error: | |
description: | | |
Error message translated based on request language header. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Invalid credentials. | |
headers: | |
set-cookie: | |
description: | | |
Unsets cookie token. | |
examples: | |
Default: | |
summary: Unset Cookie | |
value: __Host-session_id=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Strict | |
required: true | |
schema: | |
type: string | |
"406": | |
content: | |
application/json: | |
examples: | |
InvalidAcceptHeader: | |
summary: Invalid Accept Header | |
value: | |
error: expected the value "application/json" for the accept request header is expected | |
InvalidContentTypeHeader: | |
summary: Invalid ContentType Header | |
value: | |
error: expected the value "application/json" for the content-type request header | |
MultipleAcceptHeaders: | |
summary: Multiple Accept Headers | |
value: | |
error: exactly 1 value must be set for the accept request header | |
MultipleContentTypeHeaders: | |
summary: Multiple ContentType Headers | |
value: | |
error: exactly 1 value must be set for the content-type request header is expected | |
schema: | |
properties: | |
error: | |
description: | | |
Error message is not translated as it is not expected that the invalid request body is caused by the end-user, so as the response message will be. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Request headers are not accepted. | |
"500": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Internal server error occurred. Please try again later, and inform support if the error persists. | |
schema: | |
properties: | |
error: | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Internal error occurred. The error might be retryable if the respective header exists in the response. | |
headers: | |
falomen-should-retry: | |
deprecated: false | |
description: | | |
Optional header indicating whether the request should be retried by the client. It always have the value of `true` if present, i.e., only checking whether the header is present in the response body would suffice. | |
examples: | |
ShouldRetry: | |
summary: Should Retry Request | |
value: "true" | |
required: false | |
schema: | |
const: "true" | |
type: string | |
summary: Refresh Token | |
tags: | |
- Authentication | |
/api/v1/auth/signin-google: | |
post: | |
deprecated: false | |
description: | | |
User will be registered if hasn't been already. | |
operationId: signinWithGoogle | |
parameters: | |
- deprecated: false | |
description: | | |
If provided, will be used as the target language to translate messages into according to [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt). | |
Read more at: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language>. | |
If the specified language is not supported, it will fallback to `en-US` (American English). | |
Language of the response will be set in the `content-language` header. See: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language> | |
examples: | |
ChineseWithFallback: | |
summary: Chinese with Fallback to English | |
value: cn,en-US | |
English: | |
summary: American English | |
value: en-US | |
NotSupported: | |
summary: Not-supported Language | |
value: xyz | |
in: header | |
name: accept-language | |
required: false | |
schema: | |
type: string | |
requestBody: | |
content: | |
application/json: | |
examples: | |
Accepted: | |
summary: Accepted Google Credential Token | |
value: | |
googleTokenCredential: eyJhbGciOiJSUzI1NiIsImtpZCI6IjdjMGI2OTEzZmUxMzgyMGEzMzMzOTlhY2U0MjZlNzA1MzVhOWEwYmYiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJuYmYiOjE2OTQ1OTUwNDQsImF1ZCI6IjI1NDgxMTMzMTYxNy01M29xc2lma3VlYmkwMGVub2pmMTAyY2dtNWVpZTkzaS5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsInN1YiI6IjEwMzYzMzE5NjY2OTgwODg1MDMwNCIsImVtYWlsIjoiMmhvdG92ZXJvb0BnbWFpbC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiYXpwIjoiMjU0ODExMzMxNjE3LTUzb3FzaWZrdWViaTAwZW5vamYxMDJjZ201ZWllOTNpLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29tIiwibmFtZSI6IlJvc2FyaW8gU29mw61hIEFybWlqbyBNZWRpbmEiLCJwaWN0dXJlIjoiaHR0cHM6Ly9saDMuZ29vZ2xldXNlcmNvbnRlbnQuY29tL2EvQUNnOG9jSjQwRXhJeF9nVHdNbUVZdHp5MmNaay1DQzk2dElqQ3NiRERNdFByUFkxPXM5Ni1jIiwiZ2l2ZW5fbmFtZSI6IlJvc2FyaW8gU29mw61hIEFybWlqbyIsImZhbWlseV9uYW1lIjoiTWVkaW5hIiwiaWF0IjoxNjk0NTk1MzQ0LCJleHAiOjE2OTQ1OTg5NDQsImp0aSI6IjI2ZmMyZWQxZTMwYzNiYzNiYzYyYTg3OTYxMjFkZjM0NGRkMmJjOGIifQ.cjkhbiHXW727-EP_4CJ0L66xJ_ud7gyrwALrPPgkV7RlEF4aBl3wl7VZvkycOGQHoBRkPTZCrKeKrrmV8tbu-x0kiCNfL6BFavwNIzssC2o4nInTBQ1GFwBCPCSEZ9gCPDhayNC2_KYBt_E62oBmOm2YtX0Q8MvwOkQz81SxNHJg5Ke0F9dcMfKBrTppCm10qVOBhOMkqexwI1lkQtlNXTSoWhwRKtHl60uMeBUmlP44gEhQUaIvJF5giYDyQACvwWFoLUWsvQelugIU_A7FLirPn-1HOCkmHqBdPHX3YXPSdEGLD4IsILenM2FyrM-h-p5AeomP6mhaZzZS6--l2A | |
schema: | |
properties: | |
googleTokenCredential: | |
description: | | |
JWT token received from Google upon successful user authentication. | |
Usually it is one of the properties passed into the callback function registered into the respective Google authentication SDK that gets called upon successful authentication. | |
maxLength: 2000 | |
title: Google Token Credential | |
type: string | |
required: | |
- googleTokenCredential | |
type: object | |
unevaluatedProperties: false | |
responses: | |
"201": | |
content: | |
application/json: | |
examples: | |
Successful: | |
summary: Successful Signin | |
value: | |
bearerToken: eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTU5ODIwMTIsImlhdCI6MTY5NTM3NzIxMiwiaXNzIjoiYXV0aC5mYWxvbWVuIiwianRpIjoiUWtoNVNwX2tfaVZDai05bFhrb1J3dExGX1pjRVZadXpUNnEweU1VdFl2Qk0tdkd0WjJFaHM0TFoyR0dHb1A3TGltNFY4aUh3NklWOVQ0ci1QalRobGVjQ0FfY1ZBRkwxd2tZUjQ0amFWZkViQzNlb3U3d0ExNzdaNUR3eXE2WFAiLCJzZXNzaW9uX2lkIjoiMlFicWpETnVhNnFILXdiVFJzYkR6QzcyQTZVTWRyR1l2SktZZHVzMjVhbVdZdVhPWGl2cTlxOHJQSDdCbGd6dUtkQUs2WVNMak5iWEM3ZHZ1T1hXOFh0aGxtNlp2SkdHN1dQUiIsInN1YiI6Im9KWW1Bb3ZhV09mdmNzcGFWTVIyIn0.P3QWD_qiL_ixCQRi8iQ_dkEPuneTPlzlxirVoBjCOMJf_hfOOydy6slCNEU_ylEueL3waiusQsmQYflCR6jnDA | |
expiresAt: "2023-09-29T10:06:52Z" | |
refreshToken: ZTgltjs27StJr9bRfpK-N52_OccwC8q3Rm7pFLwyoUmYDjxGN6l8nVFdN7f-x0swiUsLIC6nqwBq-KH6o7TTcattihQV4u-3vtluUIgv6oNWCXEdQKNdbqwjte4Jy5iBUkAV4I11XCPuEo0CjvV5h0H6kY5snEwN2wHYHZ4VXVlessEjkasN55-NBhTBYraWA6hLpc-2NHpFNyEDn3br8bWOiq4GrkHKdWKUtB-ZENdU9HKf9Xskpva_XpQBWBoXuR7oA3llQ1Lp0AiQ9eHCD7QukZFPxCL1qmDWf2h9n24RiYvbn5L8jHNZc5YLC1cixry4TR7diOIqp0aDq5ucuIThoO4Sfispg6HXFG6_viaoMRmLY2_Epr3JQldg3eXDk5HJ2a-XeWlRCJZSU_R-e4GvG5C1Nhn2dWLLkHrOSKxxCBENJ1BZiVgpMTAzIOXBTXCwPsVDXO7piTKU6sf9Qs-tJ3i2SpqHvDwFc37iMqyP_Wryfe46uVV4EdewB5otZ9vBmQupS7d0QAu5GLu9G-VAlk9B9HoZ1_LkyDoSSd0Kv_s4J86VNszL-CtKTzxVeD4UNtJqbbwHQbxSpFocZYKiiY3GQaLVXgWcTAwsyBE66uwDra7Fqf8cqDy5DEeeYSteb8G7TghoJvMjtLDbszWzmCkgRcYcUyn4cuTABu9g-f4Ntn-tign7ck8zpPjeGh6AlVhLoGjDwkK8sfAPFHtWuxLLHRyaf7tStZwmEFpST5zP3FIq6Tf-4gFnPzfqSk-vP1qBhy2ThDVjidinpYV2C7-CBhIOEzpXr7lu3xcLhgu_Y4pSH3BLPwSDyYlIZxWVW1xlnKknAvEG8rwcENSr3Bw0i1HGjYmYv2lSlqo4rqChLY34KnQO7nXiURT2kXp0WQSiDB_Bfujfjjh7UI9_g51l1-KGMpho_bt1fLp8B-_vX8YoDPDZ8vEDcOIDLQGSUQU0tEBpSGJtzlFN95hpxwfm25J2ZRNUJSeBnCFp5gjefien0OGLuz_yFv37 | |
refreshTokenExpiresAt: "2023-10-20T10:06:52Z" | |
schema: | |
properties: | |
bearerToken: | |
description: | | |
Bearer token in JWT format that must be provided in the `authorization` request header. | |
title: Bearer Token | |
type: string | |
expiresAt: | |
description: | | |
Bearer token expiration date time in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. The token should not be used after expiration. Doing so, will result in the session termination. | |
maxLength: 20 | |
minLength: 20 | |
title: Bearer Token Expiration Time | |
type: string | |
refreshToken: | |
description: | | |
Refresh token that must only be used with the respective API after expiration of the Bearer Token to receive a new token falimiy. | |
title: Refresh Token | |
type: string | |
refreshTokenExpiresAt: | |
description: | | |
Refresh token expiration date time in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. If the token is not used to receive a new token set before expiration, the session will be terminated. | |
maxLength: 20 | |
minLength: 20 | |
title: Refresh Token Expiration Time | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Signin is successfull, and new session is created. | |
headers: | |
set-cookie: | |
description: | | |
Sets cookie token. | |
examples: | |
Example: | |
summary: Cookie Token | |
value: __Host-session_id=JG9nXLC01esyq4vTZUcJ4xM00RMd8HU0WjsVEhIR-fSqz0ubWo9ND9ygLHCqT2Q5r9TKzqh8VgPl9Xx6CfQ5bhbxn_pbMF7OBSMnXR1oWy0yME5rNLs8x0BKEqHavapf; Path=/; Expires=Mon, 02 Oct 2023 02:14:20 GMT; HttpOnly; Secure; SameSite=Strict | |
required: true | |
schema: | |
type: string | |
"400": | |
content: | |
application/json: | |
examples: | |
InvalidAccountInfo: | |
summary: Invalid Account Info | |
value: | |
error: Email address exceeds maximum characters length of 256 characters. | |
InvalidBody: | |
summary: Invalid Body | |
value: | |
error: Invalid request payload. | |
schema: | |
properties: | |
error: | |
description: | | |
Error message translated based on request language header. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: | | |
Request body is invalid. Make sure request body is compatible with the validation rules defined the request body section. | |
It might also happen due to invalid user's Google account information that we cannot signin, or register the user, which in this, the returned error is inteded to be shown directly to the user without any additional processing. | |
"401": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Incorrect credentials. | |
schema: | |
properties: | |
error: | |
description: | | |
Error message translated based on request language header. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Invalid credentials. | |
"406": | |
content: | |
application/json: | |
examples: | |
InvalidAcceptHeader: | |
summary: Invalid Accept Header | |
value: | |
error: expected the value "application/json" for the accept request header is expected | |
InvalidContentTypeHeader: | |
summary: Invalid ContentType Header | |
value: | |
error: expected the value "application/json" for the content-type request header | |
MultipleAcceptHeaders: | |
summary: Multiple Accept Headers | |
value: | |
error: exactly 1 value must be set for the accept request header | |
MultipleContentTypeHeaders: | |
summary: Multiple ContentType Headers | |
value: | |
error: exactly 1 value must be set for the content-type request header is expected | |
schema: | |
properties: | |
error: | |
description: | | |
Error message is not translated as it is not expected that the invalid request body is caused by the end-user, so as the response message will be. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Request headers are not accepted. | |
"409": | |
content: | |
application/json: | |
examples: | |
EmailAlreadyRegistered: | |
summary: Email Already Registered | |
value: | |
error: Email address is already registered, but with a different provider. | |
schema: | |
properties: | |
error: | |
description: | | |
Error message is not translated as it is not expected that the invalid request body is caused by the end-user, so as the response message will be. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Email is already registered, but with a different auth provider. | |
"500": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Internal server error occurred. Please try again later, and inform support if the error persists. | |
schema: | |
properties: | |
error: | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Internal error occurred. The error might be retryable if the respective header exists in the response. | |
headers: | |
falomen-should-retry: | |
deprecated: false | |
description: | | |
Optional header indicating whether the request should be retried by the client. It always have the value of `true` if present, i.e., only checking whether the header is present in the response body would suffice. | |
examples: | |
ShouldRetry: | |
summary: Should Retry Request | |
value: "true" | |
required: false | |
schema: | |
const: "true" | |
type: string | |
summary: Signin with Google | |
tags: | |
- Authentication | |
- User | |
/api/v1/users: | |
get: | |
deprecated: false | |
operationId: usersList | |
parameters: | |
- deprecated: false | |
description: | | |
If provided, will be used as the target language to translate messages into according to [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt). | |
Read more at: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language>. | |
If the specified language is not supported, it will fallback to `en-US` (American English). | |
Language of the response will be set in the `content-language` header. See: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language> | |
examples: | |
ChineseWithFallback: | |
summary: Chinese with Fallback to English | |
value: cn,en-US | |
English: | |
summary: American English | |
value: en-US | |
NotSupported: | |
summary: Not-supported Language | |
value: xyz | |
in: header | |
name: accept-language | |
required: false | |
schema: | |
type: string | |
responses: | |
"200": | |
content: | |
application/json: | |
examples: | |
Default: | |
summary: Users List | |
value: | |
users: | |
- firstName: Steven | |
id: 63TtWU9zoe-s-IS87rIK | |
joinedAt: "2023-10-20T10:06:52Z" | |
lastName: Thomas | |
- firstName: Brandon | |
id: wqU2pV8FVA3ipx1WW3X- | |
joinedAt: "2023-10-21T10:06:52Z" | |
lastName: Ryder | |
- firstName: Ira | |
id: K6by7c32hlYfthZk96Ro | |
joinedAt: "2023-10-22T10:06:52Z" | |
lastName: Ingram | |
- firstName: Robert | |
id: X7fmlXgGylAtcpkrTWIL | |
joinedAt: "2023-10-23T10:06:52Z" | |
lastName: Reid | |
- firstName: Leslie | |
id: G9Ise2BrJkBbUqga3aT_ | |
joinedAt: "2023-10-24T10:06:52Z" | |
lastName: McCullough | |
- firstName: Paul | |
id: kL113T656pat8r8m1y5h | |
joinedAt: "2023-10-25T10:06:52Z" | |
lastName: Fink | |
- firstName: Steven | |
id: of2LeiqxPZoh8jk0TOnu | |
joinedAt: "2023-10-26T10:06:52Z" | |
lastName: Rodriquez | |
schema: | |
properties: | |
users: | |
items: | |
properties: | |
firstName: | |
maxLength: 256 | |
title: User First Name | |
type: string | |
id: | |
description: | | |
`20` characters long user ID | |
maxLength: 20 | |
minLength: 20 | |
title: User ID | |
type: string | |
joinedAt: | |
description: | | |
Date time user joined in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. | |
title: User Joined At | |
type: string | |
lastName: | |
maxLength: 256 | |
title: User Last Name | |
type: string | |
title: User | |
type: object | |
unevaluatedProperties: false | |
maxItems: 15 | |
minItems: 0 | |
title: Users | |
type: array | |
uniqueItems: true | |
type: object | |
unevaluatedProperties: false | |
description: Operation is successful. | |
"401": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Incorrect credentials. | |
schema: | |
properties: | |
error: | |
description: | | |
Error message translated based on request language header. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Invalid credentials. | |
headers: | |
set-cookie: | |
description: | | |
Unsets cookie token. | |
examples: | |
Default: | |
summary: Unset Cookie | |
value: __Host-session_id=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Strict | |
required: true | |
schema: | |
type: string | |
"403": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Access denied. | |
schema: | |
properties: | |
error: | |
description: | | |
Error message translated based on request language header. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Access denied. User is not allowed to retrieve the list of users. | |
"406": | |
content: | |
application/json: | |
examples: | |
InvalidAcceptHeader: | |
summary: Invalid Accept Header | |
value: | |
error: expected the value "application/jsont request header is expected | |
InvalidContentTypeHeader: | |
summary: Invalid ContentType Header | |
value: | |
error: expected the value "application/json" for the content-type request header | |
MultipleAcceptHeaders: | |
summary: Multiple Accept Headers | |
value: | |
error: exactly 1 value must be set for the accept request header | |
MultipleContentTypeHeaders: | |
summary: Multiple ContentType Headers | |
value: | |
error: exactly 1 value must be set for the content-type request header is expected | |
schema: | |
properties: | |
error: | |
description: | | |
Error message is not translated as it is not expected that the invalid request body is caused by the end-user, so as the response message will be. | |
title: Error Message | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Request headers are not accepted. | |
"500": | |
content: | |
application/json: | |
examples: | |
English: | |
summary: American English Response | |
value: | |
error: Internal server error occurred. Please try again later, and inform support if the error persists. | |
schema: | |
properties: | |
error: | |
type: string | |
type: object | |
unevaluatedProperties: false | |
description: Internal error occurred. The error might be retryable if the respective header exists in the response. | |
headers: | |
falomen-should-retry: | |
deprecated: false | |
description: | | |
Optional header indicating whether the request should be retried by the client. It always have the value of `true` if present, i.e., only checking whether the header is present in the response body would suffice. | |
examples: | |
ShouldRetry: | |
summary: Should Retry Request | |
value: "true" | |
required: false | |
schema: | |
const: "true" | |
type: string | |
security: | |
- bearerToken: [] | |
cookieToken: [] | |
summary: Users List | |
tags: | |
- Admin | |
- User | |
tags: | |
- description: APIs related to users | |
name: User | |
- description: APIs related to admin users | |
name: Admin | |
- description: User authentication APIs | |
name: Authentication |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment