/
Retailer-owned AI agent

Retailer-owned AI agent

Introduction

Before diving into authentication process, we recommend reading:

  • OneStock MCP – understand the protocol and how OneStock implements it

  • Supported tools – explore the full catalog of available operations

  • Getting Access - understand the OAuth protocol and the two ways to access the MCP

Machine Authentication is designed for system-to-system integrations or shared AI agents.

Typical use cases include:

  • CRM connectors

  • Middleware integrations

  • Shared AI agents

  • Internal automation tools

  • Backend services

The customer receives an access token and a refresh token. The access token must be refreshed regularly using the refresh token.

Access creation

Access to the OneStock Backoffice or standard OneStock APIs does not automatically grant access to the Onestock MCP. A dedicated MCP access must be requested through your Onestock point of contact before any connection can be established.

Step 1 : Ask access to the OneStock representative

To request access, customers must contact their Onestock representative and provide the information below :

  • An admin email address

  • End user identifier: email or external ID

  • Authentication method requested : Machine

  • The list of required tools (see the section Supported tools )

  • The intended usage and external services that will interact with the MCP

The product team will take care of setting up access (within a week or the lastest).

Step 2 : Follow the creation steps by email

An initial email will be sent to the email address provided, containing a one-time link to set up the account as below.

Important: The invitation link is valid for 7 days only.

Even if you requested a machine authentication, you need to verify your email address, enter your first name and surname, and confirm that you are a human. A second email will then be sent containing a verification code.

image-20260507-162836.png

You will need to enter the verification code to confirm.

image-20260507-162845.png

Step 3 : Retrieves the required tokens

You will be automatically redirected to a single-page link showing the tokens required for your application to connect to the MCP. You will find two types of tokens :

  • Access token: A short-lived JWT that proves your identity on every request to the MCP server. It is passed as an Authorization: Bearer <access_token> header. Access tokens expire every 15 minutes.

  • Refresh token: A longer-lived, single-use token that allows you to obtain a new access token without re-authenticating from scratch.

 

Step 4 : Implement the refresh mechanism in your application

The Onestock MCP, using this token-based method, can be accessed via this URL below.

https://mcp-authkit.eu1.onestock-retail.com

Each request requires two pieces of authentication information:

  • Access Token: To be filled in the Authorization header as Bearer <access_token>.

The OneStock MCP server verifies the token using the JWKS endpoint published by AuthKit (RS256 signature), then resolves your identity through the WorkOS API and grants access based on your permissions.

You will need to implement the refresh token mechanism in your application, as recommended in the official OAuth 2.0 documentation : https://www.oauth.com/oauth2-servers/making-authenticated-requests/refreshing-an-access-token/?utm_source=chatgpt.com

Access tokens are short-lived by design. When an access token expires, the MCP server will reject your requests with an HTTP 401 error. To maintain an uninterrupted session, you need to refresh the token before it expires.

This is done by calling thehttps://workos.com/docs/reference/authkit/authentication#authenticate-with-refresh-token :

POST /user_management/authenticate grant_type: refresh_token

with the following parameters:

  1. clientId - your WorkOS client ID

  2. refreshToken -- the current refresh token

The response returns:

  1. A new accessToken -- to replace the expired one

  2. A new refreshToken -- to replace the one you just used

Important: Refresh tokens are single-use. Each time you refresh, WorkOS issues a new refresh token and invalidates the previous one. You must always store and use the latest refresh token. Reusing an old refresh token will fail and require a full re-authentication

Once your application is logged in, you can call the endpoint /list_tools to get all the available tools.

 

Step 5 (optional) : Integrating the AI Agent into a end-customer portal

The AI agent can be directly integrated into your website, specifically within the client portal. In this scenario, additional security measures are required to ensure that one client cannot access another client’s data.

Mandatory Steps:

  1. Client Authentication in your portal: Ensure that the AI agent is only accessible when the client is logged into your website.

  2. Client Identification in the MCP: Transmit the client’s identity to OneStock via the header below :

    1. customer_id: A custom header. Its value must be the user's email or external_id.

Important: The email or external_id security must be set up with your MCP account by your OneStock contact


Once these steps are implemented, OneStock will handle the necessary security protocols to prevent any unauthorized access between clients. This includes session isolation, data partitioning, and access controls tailored to each client’s profile.

By following these guidelines, you can safely provide AI-powered assistance directly within your client portal while maintaining strict data privacy and security standards.