---
title: Authentication State API
description: >-
  The Authentication State API provides the buyer's current authentication
  status in customer accounts. Use it to conditionally render content based on
  whether the buyer is fully signed in or viewing through a tokenized link.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/account-apis/authentication-state-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/account-apis/authentication-state-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# Authentication State API

The Authentication State API provides the buyer's current authentication status in customer accounts. Use it to conditionally render content based on whether the buyer is fully signed in or viewing through a tokenized link.

### Use cases

* **Conditional content rendering**: Show different UI depending on whether the buyer is fully authenticated or viewing the page through a pre-authenticated link.
* **Prompt for sign-in**: Detect when a buyer is pre-authenticated and display a message encouraging them to sign in for a richer experience.
* **Protect sensitive data**: Only display detailed customer information when the buyer is fully authenticated.

### Support Targets (10)

### Supported targets

* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)

### Properties

The Authentication State API object provides the buyer's authentication state. Access the following properties on the API object to read authentication data.

* **authenticationState**

  **StatefulRemoteSubscribable\<AuthenticationState>**

  **required**

  The buyer's current authentication state on the **Order status** page. The value is either `'fully_authenticated'` (the buyer is logged in) or `'pre_authenticated'` (the buyer is viewing through a tokenized link).

### AuthenticationState

The buyer’s authentication state on the \*\*Order status\*\* page: - \`'fully\_authenticated'\`: The buyer has logged in to their customer account. - \`'pre\_authenticated'\`: The buyer accessed the page through a tokenized link without logging in.

```ts
'fully_authenticated' | 'pre_authenticated'
```

Examples

### Examples

* ####

  ##### Description

  Read the buyer's authentication state and display whether they're fully authenticated or pre-authenticated. This example uses the \`useAuthenticationState\` hook to render the current status as text.

  ##### React

  ```tsx
  import {
    reactExtension,
    useAuthenticationState,
  } from '@shopify/ui-extensions-react/customer-account';
  import {Banner, Text} from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const authState = useAuthenticationState();
    return (
      <Banner status={authState === 'fully_authenticated' ? 'success' : 'warning'}>
        <Text>
          {authState === 'fully_authenticated'
            ? 'You are fully logged in.'
            : 'You are viewing this page through a shared link.'}
        </Text>
      </Banner>
    );
  }
  ```

  ##### TS

  ```ts
  import {extension, Banner, Text} from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const authState = api.authenticationState.current;
      const banner = root.createComponent(
        Banner,
        {status: authState === 'fully_authenticated' ? 'success' : 'warning'},
      );
      banner.appendChild(
        root.createComponent(
          Text, {},
          authState === 'fully_authenticated'
            ? 'You are fully logged in.'
            : 'You are viewing this page through a shared link.',
        ),
      );
      root.appendChild(banner);
    },
  );
  ```

* ####

  ##### Description

  Show different content depending on whether the buyer is fully authenticated or pre-authenticated. This example uses \`useAuthenticationState\` to conditionally render a full dashboard or a limited view.

  ##### React

  ```tsx
  import {
    reactExtension,
    useAuthenticationState,
  } from '@shopify/ui-extensions-react/customer-account';
  import {BlockStack, Text, Link} from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const authState = useAuthenticationState();

    if (authState !== 'fully_authenticated') {
      return <Text appearance="subdued">Log in to see personalized recommendations.</Text>;
    }

    return (
      <BlockStack>
        <Text emphasis="bold">Recommended for you</Text>
        <Link to="https://example.com/recommendations">View recommendations</Link>
      </BlockStack>
    );
  }
  ```

  ##### TS

  ```ts
  import {extension, BlockStack, Text, Link} from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const authState = api.authenticationState.current;

      if (authState !== 'fully_authenticated') {
        root.appendChild(
          root.createComponent(Text, {appearance: 'subdued'}, 'Log in to see personalized recommendations.'),
        );
        return;
      }

      const stack = root.createComponent(BlockStack, {});
      stack.appendChild(root.createComponent(Text, {emphasis: 'bold'}, 'Recommended for you'));
      stack.appendChild(root.createComponent(Link, {to: 'https://example.com/recommendations'}, 'View recommendations'));
      root.appendChild(stack);
    },
  );
  ```

* ####

  ##### Description

  Check the authentication state before allowing the buyer to perform sensitive actions. This example uses \`useAuthenticationState\` to gate a button behind full authentication.

  ##### React

  ```tsx
  import React, {useState} from 'react';
  import {
    reactExtension,
    useAuthenticationState,
    useApi,
  } from '@shopify/ui-extensions-react/customer-account';
  import {Banner, Button, Text} from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const authState = useAuthenticationState();
    const {requireLogin} = useApi<'customer-account.order-status.block.render'>();
    const [loading, setLoading] = useState(false);

    if (authState === 'fully_authenticated') {
      return <Button onPress={() => {}}>Manage subscription</Button>;
    }

    return (
      <Banner status="warning">
        <Text>Log in to manage your subscription.</Text>
        <Button
          disabled={loading}
          onPress={async () => {
            setLoading(true);
            await requireLogin();
            setLoading(false);
          }}
        >
          Log in
        </Button>
      </Banner>
    );
  }
  ```

  ##### TS

  ```ts
  import {extension, Banner, Button, Text} from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const authState = api.authenticationState.current;

      if (authState === 'fully_authenticated') {
        root.appendChild(root.createComponent(Button, {onPress: () => {}}, 'Manage subscription'));
        return;
      }

      const banner = root.createComponent(Banner, {status: 'warning'});
      banner.appendChild(root.createComponent(Text, {}, 'Log in to manage your subscription.'));
      banner.appendChild(
        root.createComponent(Button, {onPress: async () => { await api.requireLogin(); }}, 'Log in'),
      );
      root.appendChild(banner);
    },
  );
  ```

***

## Best practices

* **Gate sensitive actions behind full authentication**: Use the authentication state to restrict actions like editing order details to fully authenticated buyers.
* **Provide fallback content for pre-authenticated buyers**: Pre-authenticated buyers access the page through a tokenized link. Show limited information and offer a sign-in prompt for additional actions.

***

## Limitations

* The authentication state is read-only. You can't change the buyer's authentication level directly — use the [Require Login API](https://shopify.dev/docs/api/customer-account-ui-extensions/target-apis/account-apis/require-login-api) to prompt them to log in.
* Pre-authenticated buyers may have limited access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data), which can cause some API properties to return `undefined`.

***