{"openapi":"3.1.0","info":{"title":"Memo Bank Marketplace","description":"The Memo Bank Marketplace allows third-party developers to build integrations for Memo Bank customers. \n\nMarketplace applications use the same API as our customers, with an OAuth2 layer on top to access resources on their behalf.\n\nThis documentation only covers the marketplace-specific concerns. For the remaining API reference, see the [Memo Bank API documentation](https://docs.api.memo.bank).\n","version":"1.0"},"servers":[{"url":"https://api.memo.bank","description":"Production"},{"url":"https://api.sandbox.memo.bank","description":"Sandbox"}],"tags":[{"name":"OAuth2","description":"OAuth2 token management endpoints.\n"}],"paths":{"/oauth2/token":{"post":{"tags":["OAuth2"],"summary":"Create an access token","operationId":"createToken","requestBody":{"content":{"application/json":{"schema":{"type":"object","discriminator":{"propertyName":"grant_type","mapping":{"authorization_code":"#/components/schemas/AuthorizationCodeGrant","refresh_token":"#/components/schemas/RefreshTokenGrant"}},"oneOf":[{"$ref":"#/components/schemas/AuthorizationCodeGrant"},{"$ref":"#/components/schemas/RefreshTokenGrant"}]}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth2Token"}}}}},"security":[{"JWT":[]}]}}},"components":{"schemas":{"OAuth2Token":{"required":["access_token","connection_id","expires_in","refresh_token","scope","token_type"],"type":"object","properties":{"access_token":{"type":"string","description":"The access token."},"token_type":{"type":"string","description":"The token type.","example":"bearer"},"expires_in":{"type":"integer","description":"The lifetime of the access token in seconds.","format":"int64","example":3600},"refresh_token":{"type":"string","description":"The refresh token."},"scope":{"type":"string","description":"Space-separated list of granted scopes."},"connection_id":{"type":"string","description":"ID of the connection this token is linked to.","format":"uuid"}}},"AuthorizationCodeGrant":{"required":["client_id","client_secret","code","redirect_uri"],"type":"object","allOf":[{"$ref":"#/components/schemas/CreateOauth2TokenDTODiscriminator"},{"type":"object","properties":{"code":{"type":"string","description":"Authorization code received from the authorization endpoint."},"redirect_uri":{"type":"string","description":"Redirect URI used in the authorization request."},"client_id":{"type":"string","description":"OAuth2 client identifier."},"client_secret":{"type":"string","description":"OAuth2 client secret."}}}]},"CreateOauth2TokenDTO":{"type":"object","discriminator":{"propertyName":"grant_type","mapping":{"authorization_code":"#/components/schemas/AuthorizationCodeGrant","refresh_token":"#/components/schemas/RefreshTokenGrant"}},"oneOf":[{"$ref":"#/components/schemas/AuthorizationCodeGrant"},{"$ref":"#/components/schemas/RefreshTokenGrant"}]},"RefreshTokenGrant":{"required":["client_id","client_secret","refresh_token"],"type":"object","allOf":[{"$ref":"#/components/schemas/CreateOauth2TokenDTODiscriminator"},{"type":"object","properties":{"refresh_token":{"type":"string","description":"Refresh token received from a previous token request."},"client_id":{"type":"string","description":"OAuth2 client identifier."},"client_secret":{"type":"string","description":"OAuth2 client secret."},"scope":{"type":"string","description":"Space-separated list of scopes. Must be a subset of original scopes."}}}]},"CreateOauth2TokenDTODiscriminator":{"required":["grant_type"],"type":"object","properties":{"grant_type":{"type":"string"}}}}},"x-topics":[{"title":"Getting started","content":"[Contact us](mailto:openbanking@memo.bank) to apply for a marketplace application registration.\n\nTo register, you'll need:\n- A **private key** to sign the JWT to authenticate your requests;\n- A set of **scopes** your application will have access to;\n- One or more **redirect URIs** to be used during the OAuth2 flow.\n\n\nUpon registration, you'll receive the following pieces of information:\n- A **certificate** and its SHA256 thumbprint to identify your application;\n- A **secret code** to include in the JWT to authenticate your requests;\n- A **client ID** to identify your application when using the OAuth2 flow;\n- A **client secret** to authenticate your OAuth2 token requests;\n- A **token** to authenticate our requests to your webhook.\n\nKeep your secrets secure and never expose them in client-side code.\n"},{"title":"Authorization flow","content":"Marketplace applications make use of the standard OAuth2 Authorization Code flow:\n\n**1. Redirect the user to the authorization page**\n\nRedirect the user's browser to `https://client.memo.bank/authorize` with the following query parameters:\n- `client_id` — your application's client ID;\n- `redirect_uri` — one of your registered redirect URIs;\n- `scope` — space-separated list of requested scopes;\n- `state` — an opaque value to maintain state between the request and callback.\n\n**2. User approves access**\n\nThe user reviews the requested permissions and approves. They are then redirected to your `redirect_uri` with a `code` in the query parameters.\n\nIf the user denies the access or if an error occurs, they are redirected to your `redirect_uri` with an `error` and optionally an `error_description` in the query parameters. \n\n**3. Exchange the code with a token**\n\nMake a `POST` request to `/oauth2/token` using the `authorization_code` grant type, along with the `code` you received during the previous step, as well as your `redirect_uri`, `client_id` and `client_secret`.\n\nSee the API reference for the [OAuth2 token endpoint](#operation-createtoken) below for more details.\n\n**4. Refresh your access tokens**\n\nUse the `refresh_token` grant type to obtain new access and refresh tokens without requiring the user to re-authorize your  application.\n\n**Token lifetimes:**\n- Access token: **2 hours**.\n- Refresh token: **14 days** (single use).\n- Authorization code: **5 minutes** (single use).\n"},{"title":"Connection lifecycle","content":"A connection represents the link between your application and a user on a specific Memo Bank workspace. A single connection can exist for a user/workspace pair at a given time.\n\nThe ID of the connection can be retrieved from the [OAuth2 token endpoint](#operation-createtoken) and will be sent along events to the application's webhooks.\n\nWhen a user deactivates a connection, requests to the API will fail with an `inactive_connection` error code.\n"},{"title":"Authentication","content":"Marketplace applications authenticate themselves using the same JWT scheme as described in the [Memo Bank API documentation](https://docs.api.memo.bank/#doc-authentication). The only difference being that the JWT must be sent in the `X-Memo-Signature` header, while the `Authorization` header must be used to send the OAuth2 access token.\n\nIn addition to the standard JWT claims, the JWT payload must include an `oat#S256` claim containing the base64url-encoded SHA-256 hash of the OAuth2 access token (`base64url(sha256(access_token))`, see [`base64url`](https://datatracker.ietf.org/doc/html/rfc7515#appendix-C)), This binds the signature to the specific access token used in the request.\n\nYour application can only access resources that fall within the granted scopes and the specific accounts the user has authorized. Attempting to access resources outside of scope will result in an error.\n\nFor the full list of available API endpoints and their required scopes, please refer to the [Memo Bank API documentation](https://docs.api.memo.bank).\n"},{"title":"Webhooks","content":"Marketplace applications can receive webhook events when something happens on a connected user's workspace. The setup and configuration of webhooks, event types, payload format, delivery behavior and retry policy are the same as described in the [Memo Bank API documentation](https://docs.api.memo.bank/group/webhook-webhook).\n\nWhen sending an event to a marketplace application, we'll include a **`X-Memo-Connection-Id`** header. This header identifies which connection is linked to the event, allowing your application to route events to the correct context.\n\nWhen using the [Webhooks endpoints](https://docs.api.memo.bank/group/endpoint-webhooks), managed webhooks will be tied to the connection linked to the OAuth2 access token when making the call. This allows you to configure a  different URL for each connection. We can also configure a global  webhook tied to your application if you only need one URL or do not want to use these endpoints.\n"}]}