---
title: Session API
description: >-
  The Session API provides access to current POS session information and secure
  authentication tokens, allowing you to retrieve shop details, user
  information, location data, and generate tokens for secure backend
  communication. The API includes both static session data and dynamic token
  generation for authenticated API calls.
api_version: 2024-04
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/standard-apis/session-api
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/standard-apis/session-api.md
---

# Session API

The Session API provides access to current POS session information and secure authentication tokens, allowing you to retrieve shop details, user information, location data, and generate tokens for secure backend communication. The API includes both static session data and dynamic token generation for authenticated API calls.

#### Use cases

* **Authentication:** Authenticate API calls to your app's backend using secure session tokens.
* **Shop context:** Customize extension behavior based on shop domain or location settings.
* **Location features:** Implement location-specific features like tax calculations or inventory checks.
* **User tracking:** Track user activity and staff member interactions for analytics.

## Support Targets (4)

### Supported targets

* [pos.​home.​modal.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-04/targets/home-screen#home-screen-action-modal-)
* [pos.​home.​tile.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-04/targets/home-screen#home-screen-tile-)
* [pos.​purchase.​post.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-04/targets/post-purchase#post-purchase-action-menu-item-)
* [pos.​purchase.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-04/targets/post-purchase#post-purchase-action-modal-)

## SessionApi

The `SessionApi` object provides access to current session information and authentication methods. Access these properties and methods through `api.session` to retrieve shop data and generate secure tokens. These methods enable secure API calls while maintaining user privacy and [app permissions](https://help.shopify.com/en/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).

* **currentSession**

  **Session**

  **required**

  Provides comprehensive information about the current POS session including shop details, user authentication, location data, and staff member information. This data is static for the duration of the session and updates when users switch locations or staff members change.

* **getSessionToken**

  **() => Promise\<string>**

  **required**

  Generates a fresh session token for secure communication with your app's backend service. Returns `undefined` when the authenticated user lacks proper app permissions. The token is a Shopify OpenID Connect ID Token that should be used in `Authorization` headers for backend API calls. This is based on the authenticated user, not the pinned staff member.

### Session

Defines information about the current POS session. Contains authentication details, location context, and configuration settings that remain constant for the duration of the session.

* shopId

  The unique identifier for the shop currently logged into POS. Use this ID for shop-specific API calls, data filtering, or configuration management. This value remains constant throughout the session and identifies the merchant's store.

  ```ts
  number
  ```

* userId

  The unique identifier for the Shopify account currently authenticated on POS. This represents the user who logged into POS with their email address and may differ from the staff member who is currently pinned in. Use for user-specific settings and authentication context.

  ```ts
  number
  ```

* shopDomain

  The domain name associated with the shop currently logged into POS. For example, "my-store.myshopify.com." Use for constructing shop-specific URLs, API endpoints, or displaying shop identification information to users.

  ```ts
  string
  ```

* locationId

  The unique identifier for the POS device's current location within the shop. Use for location-specific inventory checks, tax calculations, shipping options, or regional feature customization. This value changes when users switch between different store locations.

  ```ts
  number
  ```

* staffMemberId

  The unique identifier for the staff member currently pinned into the POS, if any. This may be different from the \`userId\` as staff members can pin in without being the authenticated user. Use for staff-specific permissions, activity tracking, or personalized workflows. Returns \`undefined\` when no staff member is pinned in.

  ```ts
  number
  ```

```ts
export interface Session {
shopId: number;
userId: number;
shopDomain: string;
locationId: number;
staffMemberId?: number;
}
```

Examples

### Examples

* #### Access current session information

  ##### Description

  Retrieve session data including staff, location, and shop information. This example demonstrates accessing \`api.session\` to get details about the current POS session like staff member ID, location, and shop domain—useful for context-aware features or logging.

  ##### React

  ```tsx
  import React, {useState} from 'react';
  import {
  reactExtension,
  useApi,
  Screen,
  Text,
  } from '@shopify/ui-extensions-react/point-of-sale';

  const SmartGridModal = () => {
  const {currentSession, getSessionToken} =
  useApi<'pos.home.modal.render'>().session;

  const {shopId, userId, locationId, staffMemberId} = currentSession;
  const [sessionToken, setSessionToken] = useState<string>();

  getSessionToken().then((newToken) => {
  setSessionToken(newToken);
  });

  return (
  <Screen name="ScreenOne" title="Screen One Title">
  <Text>
  shopId: {shopId}, userId: {userId}, locationId: {locationId}, staffId:
  {staffMemberId}
  </Text>
  <Text>sessionToken: {sessionToken}</Text>
  </Screen>
  );
  };

  export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
  ));
  ```

  ##### TS

  ```ts
  import {
  Screen,
  Stack,
  Text,
  extension,
  } from '@shopify/ui-extensions/point-of-sale';

  export default extension('pos.home.modal.render', (root, api) => {
  const {session} = api;
  const {currentSession, getSessionToken} = session;
  const {shopId, userId, locationId, staffMemberId} = currentSession;

  const screen = root.createComponent(Screen, {
  name: 'ScreenOne',
  title: 'Screen One Title',
  });

  const currentSessionText = root.createComponent(
  Text,
  {},
  `shopId: ${shopId}, userId: ${userId}, locationId: ${locationId}, staffId: ${staffMemberId}`,
  );
  const sessionTokenText = root.createComponent(
  Text,
  {},
  'sessionToken: undefined',
  );

  getSessionToken().then((newToken) => {
  sessionTokenText.children.forEach((child) => {
  sessionTokenText.removeChild(child);
  });
  sessionTokenText.appendChild(`sessionToken: ${newToken}`);
  });

  screen.appendChild(currentSessionText);
  screen.appendChild(sessionTokenText);
  root.appendChild(screen);
  });
  ```

## Best practices

* **Use appropriate identifiers:** Distinguish between `userId` (authenticated account) and `staffMemberId` (pinned staff member) to implement correct permissions and personalization logic.
* **Implement location-aware features:** Use `locationId` information.
* **Secure backend communication:** Use session tokens exclusively for backend API calls and never expose them in client-side logs or storage. validate tokens on your backend before processing requests.

## Limitations

* Session tokens are only available when the authenticated user has proper app permissions enabled. Staff members who are pinned in but not authenticated can't generate tokens.
* Session data is read-only and can't be modified through the API. Changes to shop settings, locations, or staff assignments require POS application updates.
* Session tokens should only be used for communication with your app's configured backend service and can't be used for direct Shopify API calls from the client side.