The ShopMy API uses developer keys to authenticate requests. Our API access is not yet publicly available so for the current moment you will need to grab an API developer key from your account manager or reach out to us at partners@shopmyshelf.us.

Your developer key carries many privileges, so be sure to keep it secure! Do not share your secret developer key in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

When we provide you with a developer key, we will also provide you with your unique Developer_id. Your unique developer key will be used in authorization headers in your requests for authentication. Your unique Developer_id will be used in the URL params of our OAuth route where you will direct your users to authenticate ShopMy with your application.

OAuth User Login

We have created an OAuth landing page that you can direct users of your application to so that they can authenticate with ShopMy and give your application read/write access to various parts of our platform, such as their shop and links. These permissions are enforced on the API routes within this API definition.

The following is the URL for our OAuth landing page that you should direct your users to:

https://shopmy.us/oauth?Developer_id=<YOUR_DEVELOPER_ID>&scopes=read_links,read_collections,write_links&redirect_url=<YOUR REDIRECT URL>

OAuth URL Parameter definitions:

Developer_id: The unique developer ID that we will provide you upon registration.

scopes: The user will decide which of these ShopMy permission scopes to grant your app access to. Current options are: 
        read_links (Read access to a user's product links) -- view
        write_links (Write access to a user's product links) -- view and edit
        read_collections (Read access to your shelf collections) -- view
        
        Please include all of these scopes in the OAuth URL as shown above in the example URL

redirect_url: You must register redirect urls with us for security purposes. After successful user authentication and providing scope access to your application, we will redirect the user to your specified redirect_url. You can provide us with a list of
1 or more redirect_urls, and we will register them on our end. The redirect_url here must match one of the registered urls you provided us.

Redirecting

On successful authentication and after the user provides scope access to your application from our OAuth landing page, we will redirect them to your specified redirect_url. When this is redirect occurs, we will attach an authorization code to the end of the url as a parameter. This is specific to the authenticated user, and you can use it to obtain a long term access token for the authenticated user.

We will also add a ShopMy status string to the redirect url as a parameter. The status will read either 'connected' or 'applied'. On our OAuth landing page, we give the option for users to apply to sign up if the do not have an account. In the case they apply for our waitlist, there will not be an authorization code as they do not have an account yet, but you can track the user's 'applied' status if you wish. The parameters will be attached to the redirect URL like so:

User has a ShopMy account and connected your application:
<redirect_url>?shopmy_code=<USER_AUTHORIZATION_CODE>&shopmy_status=connected

User applied for a ShopMy account:
<redirect_url>?shopmy_status=applied

Now that you have the authorization code for a user, it is straightforward to obtain a long term access token for that user.

Token Exchange

Use the following route to exchange an authorization code for a long term access token:

const response = await fetch('https://api.shopmy.us/v1/Partners/oauth-exchange-token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer <YOUR DEVELOPER KEY>`
      },
      body: JSON.stringify({
        authorizationCode: <USER AUTHORIZATION CODE>
      })
    });

On success, you will get a 200 OK response as follows:

{
  success: true,
  accessToken (string): <LONG TERM ACCESS TOKEN FOR USER>
}

🚧
Token exchange can only be done once per user for security purposes, so save the long term accessToken appropriately.

To use the long term access token in our developers API to query on behalf of a specific user, you must add it in headers along with your developer key you previously used in the Authorization header:

headers: {
  Authorization: `Bearer <YOUR DEVELOPER KEY>`,
  X-ACCESS-TOKEN: `Bearer <LONG TERM ACCESS TOKEN>
}

👍
Now you're ready to begin using the ShopMy developer API to query on behalf of an authenticated user!