Skip to content

Instantly share code, notes, and snippets.

@xeptore

xeptore/openapi.yml

Created September 28, 2023 09:42
Show Gist options
  • Save xeptore/2af2f76744691bea457698c22c96e8e8 to your computer and use it in GitHub Desktop.
Save xeptore/2af2f76744691bea457698c22c96e8e8 to your computer and use it in GitHub Desktop.
Download ZIP
openapi.yml
Raw
openapi.yml
components:
securitySchemes:
bearerToken:
bearerFormat: JWT
scheme: bearer
type: http
cookieToken:
in: cookie
name: __Host-session_id
type: apiKey
info:
contact:
email: contact@example.com
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: john.doe@example.com
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