Embedded Apps

Embedded Apps within the Merchant Dashboard offer a seamless integration experience for both Merchants and Zid Partners. These applications are integrated directly into the dashboard through an iframe, allowing merchants to access and interact with your app without leaving Zid Merchant Dashboard. This approach simplifies the user experience by embedding app functionalities within the familiar environment of the Merchant Dashboard.

Pinned Apps:

Embedded App Label:

Embedded App Itself:

Benefits for Partners

• Seamless Integration: Embed your app within Zid Merchant Dashboard for a unified merchant experience.

• Enhanced Visibility: Increase app exposure and engagement within the Merchant Dashboard.

• Simplified Access: No separate logins required, making it easier for merchants to use your app.

• Improved Security: Utilize Zid’s secure authentication and content security policies.

• Increased Adoption: Easy integration encourages more merchants to use your app’s functionalities.

• Customer Loyalty: A seamless experience fosters higher satisfaction and long-term use.

---

Authentication Flow

The Embedded Apps feature is designed to bypass the standard login procedure for third-party applications. This process is facilitated through a specific authentication flow:

1. Initial Token Storage: Once a Merchant installs the application, Partners must use designated endpoints to store a token within Zid's system. This token is crucial for the subsequent authentication steps.
2. Token Transmission: When a Merchant accesses the embedded app, the stored token is sent as a query parameter in the iframe URL. This token serves as an identifier for the Merchant, allowing the Partner's application to recognize and log in the Merchant automatically.
3. Secure Data Handling: Despite being embedded, the application retains its ability to manage its storage within the browser, including local storage and cookies.
4. New Scope Requirement: When requesting an embedded page in the Merchant Dashboard, Partners must include the embedded_apps_tokens_write scope in their authorization requests.
5. Security Recommendations: We recommend our Partners to regularly update tokens and invalidate old ones as a security measure for the Merchant's data integrity.

---

Content Security Policy

For the security of embedded applications within the Merchant Dashboard, it's essential to include the following Content-Security-Policy in the HTTP response headers of your app's web pages:

Content-Security-Policy:
  style-src 'self' 'unsafe-inline' *;
  font-src 'self' 'unsafe-inline' data: *;
  default-src 'self' *.zid.dev web.zid.sa;
  script-src 'self' 'unsafe-inline' *;
  frame-ancestors 'self' *.zid.dev web.zid.sa;
  connect-src 'self' 'unsafe-inline' *

This Content-Security-Policy should be configured in your web server or application framework to ensure that these directives are sent in the HTTP headers of every page that is part of your embedded app.

Token Expiry and Management

The expiry of tokens is at the discretion of the Partner, based on their security assessments and requirements. Regular updates to the authorization tokens are recommended.

Create / Update User Token

Partners can update the authentication token for any merchant who has installed their application. This endpoint is used to refresh the token so that the Merchant can retain secure access.

Endpoint cURL:

curl -X POST --location 'https://api.zid.sa/v1/managers/embedded-apps-token' \
--header 'Authorization: Bearer {{authorization_token}}' \
--header 'x-manager-token: {{x-manager-token}}' \
--header 'Content-Type: application/json' \
--data '{
    "token": "{your_authorization_token_for_this_merchant}"
}'

Delete User Token

When a merchant uninstalls the application, it's important to revoke their access by deleting the authorization token from Zid's system.

Endpoint cURL:

curl -X DELETE --location 'https://api.zid.sa/v1/managers/embedded-apps-token' \
--header 'Authorization: Bearer {{authorization_token}}' \
--header 'x-manager-token: {{x-manager-token}}'