OAuth 2.0 is the industry-standard protocol for authorizing apps, allowing secure access to resources without exposing sensitive data like passwords. It differs from authentication, which verifies the identity of the user or app.
At Zid, we use the authorization code grant type, which is ideal for confidential clients. This method involves redirecting the user to an authorization server, where they grant permissions to your app. Your server-side app must handle this process, as it requires securely managing the Client Secret.
Authorization Token: This token grants your app access to the Zid API.
X-MANAGER-TOKEN: This token allows access to a specific store on the Zid platform. It adds an extra layer of security, particularly when interacting with store-specific resources.
Access-Token: Used interchangeably with X-MANAGER-TOKEN in Product component API endpoints for technical reasons.
Secure Access: OAuth 2.0 ensures that your app accesses Zid resources securely without exposing sensitive information like passwords.
Scoped Permissions: Define specific access levels through scopes, allowing merchants to control what data your app can access.
Token-Based Authentication: Tokens are time-limited, reducing the risk of unauthorized access if a token is compromised. Merchants can revoke access at any time.
The first step is to retrieve an API id and API secret key, which you get when you create an app. These API credentials identify your app during the authorization process.
The installation process starts with your application via the redirection url, followed by these scenarios:
Browser redirects to the Authorize endpoint of the OAuth Server (Zid AppMarket)
If the merchant isn’t authenticated, the OAuth Server redirects to the Login page
The merchant authenticates, and is redirected back to the OAuth Server
The merchant will see the scopes that your application is requesting and approve (or decline)
The OAuth Server issues a one time token called an Authorization Code which will be sent to your application in the next step
Here is a code example (PHP/Laravel) of this method:
you will construct an API call to our OAuth server along with some required parameters as follows:
client_id => your application clinet id from the partner dashboard
redirect_uri => an endpoint your application must implemnt (see step 2)
response_type => OAuth2 flow to be used
Zid AppMarket supports many scopes to be requested from the merchant; you can select the needed scopes for your application via your application page in the Partner Dashboard
Note: In all examples, the payload is sent in the request body, not as query parameters.
the $response variable will hold all the needed data to be authenticated into that merchant store; the payload will be as follows:
access_token: to be sent with each request
Authorization: to be sent with each request
refresh_token: to refresh the token once it is expired
expires_in: the expiry date for this token (1 year)
Authorization token can be generated directly through our OAuth 2.0 server (once a merchant install your application, you will get this token via the callback method). This token will be used in your outgoing request as the authorization header.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
This token represnt an extra layer of security, and it is required to send it with Authorization token, to illustrate how your api call should look like, take a look on this sample cURL:
You will need to pass the content of access_token under the name X-Manager-Token, and Authorization for every request.
Please consider that the manager token expires in 1 year.
The data returned in this endpoint must be kept in a secure storage, abusing token might block your app.
While you are testing and developing your application, you could face some issues in the integration or during the OAuth2.0 process. We have listed the most common errors and how to solve them.
When the merchant uninstall your app, we will send you a webhook with this event and the tokens you have will be invalid.
