Zoey REST API reference · Interactive version: apidocs.zoey.com

Setup

Setup: oAuth 2.0

Zoey now has support for oAuth 2.0 Authentication. To get started using oAuth 2.0 first navigate to Settings > AP > REST - oAuth 2.0 Clients to create your first oAuth 2.0 Client.

Get Help Setting Up Postman by using our Easy To Follow Postman Setup Guide

When adding a new client you will see a Client ID and a Client Secret. These values should be kept safe and not exposed at any time.

Zoey Follows the oAuth 2.0 Standard
Learn More about oAuth 2.0 here

Clients

At the time a Client is created, it will be provided a client_id and a client_secret which can be used depending on the type of Grant Types allowed to this Client.

At anytime, a Client can be disabled. Once a Client is disabled it will no longer allow any authentication, or any access to previously granted access tokens.

At the top of the Client View there will be a button to "Revoke All Tokens". This will delete any access and refresh tokens that have been generated to be used by this client. Any integration that is using these access tokens will be forced to re authenticate.

Note:
Because the API KEY Grant Type does not use Access Tokens the only way to prevent it from making requests would be to disable the client.

Grant Types

Zoey provides workflows for a few different Grant Types which can be used according to the needs of the API integration.

Authorization Code

Use this Grant Type when the API integration requires it to call data on behalf of a user. When using this Grant Type, the user will be required to authenticate before an authorization code can be provided. Once the authorization code is provided, it can be exchanged for an access token and used to fetch data.

For extra security Zoey has built in support for PKCE. It is encouraged to use PKCE when using the Authroization Grant Type. If for some reason the platform you are using does not support it, you are able to disable.

Note:
As of right now Zoey only supports the S256 challenge method and will reject the plain
challenge method if attempted to be used.

During the initial authorization a check will be made that the redirect_uri where the authorization code is being sent to is a valid URI. We do this by allowing you to set the Allowed Redirect URI's so that a more secure validation can take place.

To Use:

  1. Create a Client that allows for the Authorization Code Grant Type. Make sure it is enabled. (Optionally it is encouraged that you enable the With PKCE setting for increased security).

  2. You need to then obtain an Authorization Code for the User you want to authenticate. This is done by redirecting the user to your stores "Authorization URL". This can be a standard GET request in a browser to https://{{ YOUR STORE CODE HERE}}/admin/oauth_authorize. This URL must contain query parameters for:
    • response_type=code
    • client_id={{ YOUR CLIENT ID }}
    • redirect_uri={{ URL WHERE YOU WANT THE CODE TO BE SENT }} ( note this must be allowed in the client settings)

    Optionally for PKCE:
    • code_challenge={{ a RANDOM base64 encoded hashed value }} ( Save the un-hashed value as it will be needed as the code_verifier when obtaining the Access Token. )
    • code_challenge_method=S256 ( note that right now Zoey only supports sha-256 hashing for the code challenge. Plain is not supported. )

  3. The User then will then be given the opportunity to either "Authorize" or "Reject" this request.

4. If the User "Authorizes". A GET request will be sent back to the redirect_uri specified with the code as a query parameter.

https://{{ YOUR REQUEST URI HERE }}?code=6aa7726b3db5e6c6fe53fa3f280d205c

5. Next you need to obtain a new Access Token using the recently obtained Authorization Code. To get this Access Token you need to make a request to your "Token URL".

curl -X POST "https://{{ YOUR STORE CODE HERE }}/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code={{ YOUR_AUTHORIZATION_CODE }}" \
     -d "redirect_uri={{ REDIRECT URI USED DURING AUTHORIZATION }}" \
     -d "client_id={{ YOUR_CLIENT_ID }}" \
     -d "client_secret={{ YOUR_CLIENT_SECRET }}"

Note:
The client_id and client_secret can either be sent in the request body OR in the Authorization Header.

curl -X POST "https://{{ YOUR STORE CODE HERE }}/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
     -d "grant_type=authorization_code" \     
     -d "code={{ YOUR_AUTHORIZATION_CODE }}" \
     -d "redirect_uri={{ REDIRECT URI USED DURING AUTHORIZATION }}"

IF using PKCE and a code_challenge was used during authoriztion. A code_verifier will be required when obtaining the Access Token. The code_verifier is the "un hashed" value of the code_challenge that was used when obtaining the authorization code. This code_verifier is a 1 time value and should be random.

curl -X POST "https://{{ YOUR STORE CODE HERE }}/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
     -d "grant_type=authorization_code" \     
     -d "code={{ YOUR_AUTHORIZATION_CODE }}" \
     -d "redirect_uri={{ REDIRECT URI USED DURING AUTHORIZATION }}" \
     -d "code_verifier={{ CODE VERIFIER }}"

The response will contain information about your Access Token and optionally a Refresh Token ( Only if that Grant Type is allowed by this Client).

{"token_type":"bearer","expires_in":3600,"created_at":1740141611,"access_token":"cf99a935ca10523b251913b51c973f5f","refresh_token":"92126beafee10ee56d2ae8980a3d9f04"}

Once you have the Access Token you are able to make requests using it in the Authorization Header.

curl https://{{ YOUR STORE CODE HERE }}/api/rest/products/ -H 'Authorization: Bearer cf99a935ca10523b251913b51c973f5f'

Refresh Token

Use this Grant Type in conjunction with the Authroization Code Grant Type to allow the API integration to easily obtain new access tokens as they expire.

To Use:

  1. Create a Client that allows for the Refresh Token Grant Type. Make sure it is enabled.

  2. Next you need to obtain a new Access Token using the previously obtained Refresh Token. To get this Access Token you need to make a request to your "Token URL".

curl -X POST "https://{{ YOUR STORE CODE HERE }}/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=YOUR_REFRESH_TOKEN" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET"

Note:
The client_id and client_secret can either be sent in the request body OR in the Authorization Header.

curl -X POST "https://{{ YOUR STORE CODE HERE }}/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
     -d "grant_type=client_credentials" \     
     -d "refresh_token=YOUR_REFRESH_TOKEN"

The response will contain information about your Access Token and your new Refresh Token.

{"token_type":"bearer","expires_in":3600,"created_at":1740141611,"access_token":"cf99a935ca10523b251913b51c973f5f","refresh_token":"92126beafee10ee56d2ae8980a3d9f04"}

Once you have the Access Token you are able to make requests using it in the Authorization Header.

curl https://{{ YOUR STORE CODE HERE }}/api/rest/products/ -H 'Authorization: Bearer cf99a935ca10523b251913b51c973f5f'

Client Credentials

This Grant Type does NOT require any user authentication. It can obtain an access token at any time and use it as needed.

To Use:

  1. Create a Client that allows for the Client Credentials Grant Type. Make sure it is enabled.

  2. Next you need to obtain an Access Token before you can start fetching data. To get this Access Token you need to make a request to your "Token URL".

curl -X POST "https://{{ YOUR STORE CODE HERE }}/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET"

Note:
The client_id and client_secret can either be sent in the request body OR in the Authorization Header.

curl -X POST "https://{{ YOUR STORE CODE HERE }}/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
     -d "grant_type=client_credentials"

The response will contain information about your Access Token.

{"token_type":"bearer","expires_in":3600,"created_at":1740141611,"access_token":"cf99a935ca10523b251913b51c973f5f"}

Once you have the Access Token you are able to make requests using it in the Authorization Header.

curl https://{{ YOUR STORE CODE HERE }}/api/rest/products/ -H 'Authorization: Bearer cf99a935ca10523b251913b51c973f5f'

Api Key

The API KEY Grant Type will bypass all authorization and can be used directly to fetch data. Unlike the other Grant Types this key will never expire and never needs to be refreshed. Because of that its very important that this value is kept safe.

To Use:

  1. Create a Client that allows for the Api Key Grant Type. Make sure it is enabled.

  2. Start Using the API Key. The value of the Api-Key header will be the client_secret that was generated when the Client was created.

curl https://{{ YOUR STORE CODE HERE }}/api/rest/products/ -H 'Api-Key: 95b1374d58c764e3aaae085b3dfce75a9c2104cbc2ab7977346f4ec121f94174'