Stateset One provides a REST and GraphQL API.

​

Authentication

It’s important to note that all data in Stateset is private by default. This means that you must authenticate with the Stateset API in order to read or write data. Stateset uses a token-based authentication system. This means that you must include your API token with every request that you make to the API. Each token depicts a user who is authenticated to your Stateset platform instance. Tokens can only be generated for signed in users and each token is tied to a particular user.

Tokens can also be generated from your Stateset Cloud Account, using tokens that are set for each user and have a variable expiry date.

A request is considered “authenticated” when the backend can securely identify which user and which device is making the request. The reasons for making authenticated requests to the backend include:

• Associating the user with the action being performed
• Ensuring the user has permission to make the request
• Keeping an audit log of which device the user is performing actions from

In order to authenticate the user on the backend using Clerk / Firebase / Stateset the short-lived session token needs to be passed to the server.

The authentication service, which generates the JWT token, includes the relevant session variables in the token’s payload. These session variables can include user-related information like the user’s ID, role, or any other custom data.

Example Claims using JWT

'Authorization': '<token>'

​

GraphQL API

​

Enable the GraphQL API for your Stateset Project

Stateset One projects come with a Hasura GraphQL API by default.

You can deploy the Stateset GraphQL API and Postgres by signing up on stateset.io/signup

Upon SignUp at stateset.io/signup you will receive an email with your Stateset One GraphQL URL

https://<your-project-name>.stateset.app/v1/graphql

​

Accessing your Stateset One Backend

You will need the Stateset Admin Secret Key to access the Stateset One GraphQL API.

​

API Access

Stateset strives to streamline all ecommerce operations for online sellers, no matter where they sell their products online. We are continuously adding new marketplaces, shopping carts, and integration tools, because we know the e-commerce space is growing. As a result, we’ve worked hard to provide developer resources to build custom integrations with Stateset.

​

Stateset API

The Stateset REST API is a great way to get data directly to and from Stateset, like creating purchase orders or retrieving returns, order, shipment and warranty data.

The Stateset REST API is available for any plan and allows developers to build applications that interface with the Stateset One Platform.

​

Permissions

Stateset’s permissions are implemented using Hasura Session Variables. Hasura is a GraphQL engine that provides fine-grained access control for tables and views. With Hasura, you can define permission rules for users based on their roles, and session variables play a crucial role in enforcing these permissions.

​

User Roles and Permissions

In Stateset, you can define your own user roles within the Hasura GraphQL Engine. User roles represent different levels of access or privileges that users can have within the system. Examples of roles could be “admin,” “manager,” or “user.”

​

Incorporating Session Variables

Permissions in Stateset usually incorporate session variables. Session variables are pieces of data that are returned from the authentication service for each request made to Stateset. They contain information about the authenticated user and their role.

​

JWT Mode

In JWT (JSON Web Token) mode, session variables are encoded into the payload of the JWT token. The authentication service, which generates the JWT token, includes the relevant session variables in the token’s payload. These session variables can include user-related information like the user’s ID, role, or any other custom data.

Example Claims using JWT

{
	"https://hasura.io/jwt/claims": {
		"x-hasura-org-id": "{{org.id}}",
		"x-hasura-user-id": "{{user.id}}",
		"x-hasura-default-role": "user",
		"x-hasura-allowed-roles": [
			"user"
		]
	}
}

​

Webhook Mode

In webhook mode, session variables are returned as a JSON object in the body of the response from the webhook. When a user makes a request to Stateset, the authentication service validates the request and returns a response containing session variables. These session variables are then used by Stateset to determine the user’s role and enforce the appropriate permissions.

​

Enforcing Permissions

With the session variables obtained from either JWT mode or webhook mode, Stateset evaluates the permissions associated with the user’s role. It checks if the user has the necessary permissions to perform the requested action on the specific table or view. If the user’s role has the required permissions, the action is allowed; otherwise, it is denied.

By utilizing Hasura Session Variables, Stateset ensures that permissions are properly enforced based on the user’s role and the associated rules defined for each table or view. This approach provides a flexible and secure way to control data access within the Stateset platform.

Example useStatesetQuery Hook using JWT based Authentication and SWR:

/**
 * Make authenticated GraphQL query request to Stateset
 * @param {string} query GraphQL query or mutation
 * @param {Object} variables GraphQL Document variables
 * @param {boolean} blockRequest Request blocked if true
 * @returns useSWR object (data, error, isValidating, mutate)
 */

export const useStatesetQuery = (query, variables, blockRequest) => {

  const { isLoaded, organization } = useOrganization();

  if (!query) {
    throw Error("No query provided to `useStatesetQuery`");
  }

  const { getToken, isSignedIn } = useAuth();

  if (!isLoaded || !isSignedIn) {

    return null;

  } else {

    const nodeName = organization.publicMetadata.nodeName;

    const endpoint = `https://${nodeName}.stateset.app/v1/graphql`;

    const fetcher = async () =>
      request(endpoint, query, variables, {
        authorization: `Bearer ${await getToken({ template: `hasura` })}`,
      });

    return useSWR(query, blockRequest ? () => { } : fetcher);
  }

};