{"id":18684665,"url":"https://github.com/getbeak/nest","last_synced_at":"2025-08-31T03:31:47.629Z","repository":{"id":42634510,"uuid":"321164633","full_name":"getbeak/nest","owner":"getbeak","description":"Serverless API powering auth, subscriptions, etc. Have a poke around","archived":true,"fork":false,"pushed_at":"2023-03-06T05:24:44.000Z","size":474,"stargazers_count":2,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-18T19:48:34.109Z","etag":null,"topics":["api","api-gateway","serverless"],"latest_commit_sha":null,"homepage":"https://nest.getbeak.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getbeak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-13T21:34:04.000Z","updated_at":"2024-11-15T00:13:09.000Z","dependencies_parsed_at":"2023-01-30T16:15:19.381Z","dependency_job_id":null,"html_url":"https://github.com/getbeak/nest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/getbeak/nest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getbeak%2Fnest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getbeak%2Fnest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getbeak%2Fnest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getbeak%2Fnest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getbeak","download_url":"https://codeload.github.com/getbeak/nest/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getbeak%2Fnest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272934224,"owners_count":25017817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-gateway","serverless"],"created_at":"2024-11-07T10:18:50.527Z","updated_at":"2025-08-31T03:31:47.207Z","avatar_url":"https://github.com/getbeak.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nest\r\n\r\nServerless API powering releases, user management, auth, etc. Have a poke around! :)\r\n\r\nProd URL: `https://nest.getbeak.app/1/`\r\nNonprod URL: `https://nest.nonprod-getbeak.app/1/`\r\n\r\n## API methods\r\n\r\nThe API has no prefix, it goes straight to the version information.\r\n\r\n**Versions**:\r\n\r\n- `2020-12-14`: Initial version\r\n- `2021-10-06`: Updated `get_subscription_status` to support new subscription states\r\n\r\n### `send_magic_link`\r\n\r\nSends a magic link enabling a user to authenticate!\r\n\r\n#### Request\r\n\r\n```json\r\n{\r\n\t\"client_id\": \"client_000000C2kdCzNlbL1BqR5FeMatItU\",\r\n\t\"redirect_uri\": \"https://magic.getbeak.app/\",\r\n\t\"state\": \"lx/rAzKFsThZ+pqne+uCQZ2OamjZtpW_GtdtUwvEaAg7t\",\r\n\t\"code_challenge_method\": \"S256\",\r\n\t\"code_challenge\": \"ec088e759677e0f799ccbe2b3a667c16037af08b0e3dff8732edbe1f42f6ef1c\",\r\n\t\"identifier_type\": \"email\",\r\n\t\"identifier_value\": \"example@getbeak.app\",\r\n\t\"device\": {\r\n\t\t\"platform\": \"mac\",\r\n\t\t\"beak_id\": \"c3f163f8-b9da-41fb-b8e5-59af2ff848cb\",\r\n\t\t\"fingerprint\": \"c601897118286408c19bb71db2cf1087975214cfcc6dd261a552b2779c8a5ec662b9808adfb98dabb7f14e5b0ea1b2c3149be2ffef2f5929758ebec68036bdee\"\r\n\t}\r\n}\r\n```\r\n\r\n- `client_id`: The ID of the client requesting the magic link.\r\n- `redirect_uri`: The redirect URI to return too, whitelisted against the client.\r\n- `state`: A web/url safe nonce generated and stored against the challenge for each requested.\r\n- `code_challenge_method`: Always `S256`.\r\n- `code_challenge`: A SHA256 digest of the code verifier, which is send in `authenticate_user`. Websafe base64 encoded.\r\n- `identifier_type`: Always `email`.\r\n- `identifier_value`: The email address to send the magic link too.\r\n- `device`: Optional field containing device information\r\n\t- `platform`: The platform Beak is running on.\r\n\t- `beak_id`: The beak specific unique session id.\r\n\t- `fingerprint`: The physical hardware id.\r\n\r\n### `authenticate_user`\r\n\r\nAuthenticates a user upon receiving the magic link from above.\r\n\r\n#### Request (`authorization_code`)\r\n\r\n```json\r\n{\r\n\t\"client_id\": \"client_000000C2kdCzNlbL1BqR5FeMatItU\",\r\n\t\"grant_type\": \"authorization_code\",\r\n\t\"redirect_uri\": \"https://magic.getbeak.app/\",\r\n\t\"code\": \"authzcode_000000BRxPaWGu0xDiHFOktPnBtKA.e2d09621646f6c104d7d6def9d1243e5fc22b0df765f8351495906c0ff2d0677\",\r\n\t\"code_verifier\": \"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"\r\n}\r\n```\r\n\r\n- `client_id`: The ID of the client requesting the magic link.\r\n- `grant_type`: Must be `authorization_code` for authenticating.\r\n- `redirect_uri`: The redirect URI whitelisted against the client.\r\n- `code`: The authorization code that we got from the magic link.\r\n- `code_verifier`: The plaintext string that was hashed in the previous step and submitted as `code_challenge`.\r\n\r\n#### Request (`refresh_token`)\r\n\r\n```json\r\n{\r\n\t\"client_id\": \"client_000000C2kdCzNlbL1BqR5FeMatItU\",\r\n\t\"grant_type\": \"refresh_token\",\r\n\t\"refresh_token\": \"01.reftok_000000C2kfdVv573A4YW7noYi2Ts8.7af10c1eb4d0c6aec372e2ea7682348b9c1d975ee6891d247117378a9e5ab4ad\"\r\n}\r\n```\r\n\r\n- `client_id`: The ID of the client requesting the magic link.\r\n- `grant_type`: Must be `authorization_code` for authenticating.\r\n- `refresh_token`: The token used to refresh the auth chain.\r\n\r\n#### Response\r\n\r\n```json\r\n{\r\n\t\"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\",\r\n\t\"token_type\": \"bearer\",\r\n\t\"expires_in\": 3600,\r\n\t\"expires_at\": \"2020-22-01T00:00:00Z\",\r\n\t\"refresh_token\": \"01.reftok_000000C2kfdVv573A4YW7noYi2Ts8.7af10c1eb4d0c6aec372e2ea7682348b9c1d975ee6891d247117378a9e5ab4ad\",\r\n\t\"user_id\": \"user_000000C2kg4d9HyP1Bg09HBF4Bm40\",\r\n\t\"client_id\": \"client_000000C2kdCzNlbL1BqR5FeMatItU\"\r\n}\r\n```\r\n\r\n### `get_subscription_status`\r\n\r\nGet's the current state of a user's subscription.\r\n\r\n#### Request\r\n\r\n```json\r\n{\r\n\t\"user_id\": \"user_000000C2kg4d9HyP1Bg09HBF4Bm40\"\r\n}\r\n```\r\n\r\n#### Response\r\n\r\n```json\r\n{\r\n\t\"status\": \"active\",\r\n\t\"billing_portal_url\": \"https://billing.stripe.com/xxx\",\r\n\t\"start_date\": \"2021-10-06T17:52:44.192Z\",\r\n\t\"end_date\": \"2022-10-06T17:52:44.192Z\"\r\n}\r\n```\r\n\r\n`billing_portal_url` can be `null` if there are issues connecting to Stripe.\r\n\r\n### `get_user`\r\n\r\nGet's information about the user.\r\n\r\n#### Request\r\n\r\n```json\r\n{\r\n\t\"user_id\": \"user_000000C2kg4d9HyP1Bg09HBF4Bm40\"\r\n}\r\n```\r\n\r\n#### Response\r\n\r\n```json\r\n{\r\n\t\"id\": \"user_000000C2kg4d9HyP1Bg09HBF4Bm40\",\r\n\t\"created_at\": \"2021-10-09T16:00:15.844Z\",\r\n\t\"identifiers\": [{\r\n\t\t\"id\": \"userident_000000C2kg4d9HyP1Bg09HBF4Bm42\",\r\n\t\t\"identifier_type\": \"email\",\r\n\t\t\"identifier_value\": \"taylor.swift@getbeak.app\",\r\n\t\t\"created_at\": \"2021-10-10T15:49:58.931Z\",\r\n\t\t\"updated_at\": \"2021-10-10T15:49:58.931Z\",\r\n\t\t\"verified_at\": \"2021-10-10T15:49:58.931Z\",\r\n\t\t\"removed_at\": null\r\n\t}]\r\n}\r\n```\r\n\r\n### `list_news_items`\r\n\r\nLists the currently available news items for a client.\r\n\r\n#### Request\r\n\r\n```json\r\n{\r\n\t\"client_id\": \"client_000\"\r\n}\r\n```\r\n\r\n#### Response\r\n\r\n```json\r\n[{\r\n\t\"id\": \"newsitem_000\",\r\n\t\"primary\": {\r\n\t\t\"code\": \"generic_banner\",\r\n\t\t\"dismissible\": false,\r\n\t\t\"payload\": {\r\n\t\t\t\"emoji\": \"💃\",\r\n\t\t\t\"title\": \"Very important message\",\r\n\t\t\t\"body\": \"You just know how important it is, you know\",\r\n\t\t\t\"action\": {\r\n\t\t\t\t\"cta\": \"Click me\",\r\n\t\t\t\t\"url\": \"https://meatspin.com/\"\r\n\t\t\t}\r\n\t\t}\r\n\t},\r\n\t\"fallback\": null\r\n}]\r\n```\r\n\r\n### `create_trial_and_magic_link`\r\n\r\nCreates a new user and subscription trial. The magic link sent to the user is trial specific, so it will open the relevant trial onboarding flow when followed.\r\n\r\n#### Request\r\n\r\n```json\r\n{\r\n\t\"client_id\": \"client_000000C2kdCzNlbL1BqR5FeMatItU\",\r\n\t\"redirect_uri\": \"https://magic.getbeak.app/\",\r\n\t\"state\": \"lx/rAzKFsThZ+pqne+uCQZ2OamjZtpW_GtdtUwvEaAg7t\",\r\n\t\"code_challenge_method\": \"S256\",\r\n\t\"code_challenge\": \"ec088e759677e0f799ccbe2b3a667c16037af08b0e3dff8732edbe1f42f6ef1c\",\r\n\t\"identifier_type\": \"email\",\r\n\t\"identifier_value\": \"example@getbeak.app\",\r\n\t\"device\": {\r\n\t\t\"platform\": \"mac\",\r\n\t\t\"beak_id\": \"c3f163f8-b9da-41fb-b8e5-59af2ff848cb\",\r\n\t\t\"fingerprint\": \"c601897118286408c19bb71db2cf1087975214cfcc6dd261a552b2779c8a5ec662b9808adfb98dabb7f14e5b0ea1b2c3149be2ffef2f5929758ebec68036bdee\"\r\n\t}\r\n}\r\n```\r\n\r\n- `client_id`: The ID of the client requesting the magic link.\r\n- `redirect_uri`: The redirect URI to return too, whitelisted against the client.\r\n- `state`: A web/url safe nonce generated and stored against the challenge for each requested.\r\n- `code_challenge_method`: Always `S256`.\r\n- `code_challenge`: A SHA256 digest of the code verifier, which is send in `authenticate_user`. Websafe base64 encoded.\r\n- `identifier_type`: Always `email`.\r\n- `identifier_value`: The email address to send the magic link too.\r\n- `device`: Optional field containing device information\r\n\t- `platform`: The platform Beak is running on.\r\n\t- `beak_id`: The beak specific unique session id.\r\n\t- `fingerprint`: The physical hardware id.\r\n\r\n\r\n### `get_marketing_consent`\r\n\r\nReturns the selected marketing consent level for a user. An error with the code `awaiting_consent` will be returned if the user hasn't set a consent level yet.\r\n\r\n#### Request\r\n\r\n```json\r\n{\r\n\t\"user_id\": \"user_000000C2kdCzNlbL1BqR5FeMatItU\"\r\n}\r\n```\r\n\r\n#### Response\r\n\r\n```json\r\n{\r\n\t\"level\": \"general\"\r\n}\r\n```\r\n\r\n- `level`: The consent level selected. Either `general` or `none`.\r\n\r\n### `set_marketing_consent`\r\n\r\nReturns the selected marketing consent level for a user. An error with the code `awaiting_consent` will be returned if the user hasn't set a consent level yet.\r\n\r\n#### Request\r\n\r\n```json\r\n{\r\n\t\"user_id\": \"user_000000C2kdCzNlbL1BqR5FeMatItU\",\r\n\t\"level\": \"general\"\r\n}\r\n```\r\n\r\n## Webhooks\r\n\r\nWebhooks URL's comprise of two parts; the webhook indicator, followed by the provider value. Each provider has an example below.\r\n\r\n### `stripe`\r\n\r\nFull path: `1/webhook/stripe`\r\n\r\nStripe webhooks are used to invoke internal logic based on changing states of a users subscription, payment, or god forbid, dispute.\r\n\r\n#### Supported events\r\n\r\n- `charge.dispute.closed`\r\n- `charge.dispute.created`\r\n- `customer.subscription.created`\r\n- `customer.subscription.deleted`\r\n- `customer.subscription.trial_will_end`\r\n- `customer.subscription.updated`\r\n- `payment_intent.canceled`\r\n- `payment_intent.created`\r\n- `payment_intent.payment_failed`\r\n- `payment_intent.processing`\r\n- `payment_intent.succeeded`\r\n\r\n## Internal data\r\n\r\nAll internal data is stored in MongoDB. All schema definitions are using TypeScript definitions.\r\n\r\n### `access_tokens`\r\n\r\n```ts\r\ninterface AccessToken {\r\n\tid: string;\r\n\tclientId: string;\r\n\tuserId: string;\r\n\tgrant: Grant;\r\n\trootGrant: Grant;\r\n\tcidrBlocks: string[];\r\n\tcreatedAt: string;\r\n\texpiresAt: string;\r\n\trevokedAt: string | null;\r\n}\r\n```\r\n\r\n### `authorizations`\r\n\r\n```ts\r\ninterface Authorizations {\r\n\tid: string;\r\n\tkey: string;\r\n\tclientId: string;\r\n\tstate: string;\r\n\tcodeChallengeMethod: 'S256';\r\n\tcodeChallenge: string;\r\n\tredirectUri: string;\r\n\tidentifierType: 'email';\r\n\tidentifierValue: string;\r\n\tcreatedAt: string;\r\n\texpiresAt: string;\r\n\tusedAt: string | null;\r\n\trevokedAt: string | null;\r\n}\r\n```\r\n\r\n### `identifiers`\r\n\r\n```ts\r\ninterface Identifiers {\r\n\tid: string;\r\n\tuserId: string;\r\n\tidentifierType: 'email';\r\n\tidentifierValue: string;\r\n\tcreatedAt: string;\r\n\tupdatedAt: string | null;\r\n\tverifiedAt: string;\r\n\tremovedAt: string | null;\r\n}\r\n```\r\n\r\n### `marketing-consent`\r\n\r\n```ts\r\ninterface MarketingConsent {\r\n\tid: string;\r\n\tuserId: string;\r\n\tlevel: 'none' | 'general';\r\n\tcreatedAt: string;\r\n\tupdatedAt: string | null;\r\n}\r\n```\r\n\r\n### `provider-mappings`\r\n\r\n```ts\r\ninterface ExternalMappings {\r\n\tid: string;\r\n\tuserId: string;\r\n\tproviderType: 'stripe';\r\n\tproviderValue: string;\r\n\tcreatedAt: string;\r\n\tremovedAt: string | null;\r\n}\r\n```\r\n\r\n### `refresh-tokens`\r\n\r\n```ts\r\ninterface RefreshTokens {\r\n\tid: string;\r\n\tkey: string;\r\n\tclientId: string;\r\n\tuserId: string;\r\n\tgrant: Grant;\r\n\trootGrant: Grant;\r\n\tcidrBlocks: string[];\r\n\tcreatedAt: string;\r\n\texpiresAt: string;\r\n\tusedAt: string | null;\r\n\trevokedAt: string | null;\r\n}\r\n```\r\n\r\n### `subscriptions`\r\n\r\n```ts\r\ninterface Subscriptions {\r\n\tid: string;\r\n\tuserId: string;\r\n\tstpProductId: string;\r\n\tstpSubscriptionId: string;\r\n\tstpCustomerId: string;\r\n\tstartsAt: string;\r\n\tendsAt: string;\r\n\tcreatedAt: string;\r\n\tupdatedAt: string | null;\r\n}\r\n```\r\n\r\n### `users`\r\n\r\n```ts\r\ninterface Users {\r\n\tid: string;\r\n\tcreatedAt: string;\r\n}\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetbeak%2Fnest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetbeak%2Fnest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetbeak%2Fnest/lists"}