Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuild with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
    Overview
    Get started
    Create an app
    How Stripe Apps work
    Sample apps
    Build an app
    Store secrets
    API authentication methods
    Authorization flows
    Server-side logic
    Listen to events
    Handle different modes
    Enable sandbox support
    App settings page
    Build a UI
    Onboarding
    Distribute your app
    Distribution options
    Upload your app
    Versions and releases
    Test your app
    Publish your app
    Promote your app
    Add deep links
    Create install links
    Assign roles in UI extensions
    Post-install actions
    App analytics
    Embedded components for Apps
    Embed third-party Stripe Apps
    Migrating to Stripe Apps
    Migrate or build an extension
    Migrate a plugin to Stripe Apps or Stripe Connect
    Reference
    App manifest
    CLI
    Extension SDK
    Permissions
    Viewports
    Design patterns
    Components
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsStripe Apps

Using roles in UI extensions

Learn how to include user roles in UI Extensions to tailor functionality to different roles.

Copy page

Stripe Apps UI extensions can read the active user’s role in the Dashboard. Apps can expose different functionality to different user roles.

The UI Extension SDK provides valuable information about the end user of your app. The roles field of the userContext object gives a list of the active user’s roles. You can tailor the app’s content based on the user’s role, using the roles in the user context.

How to determine the user’s Dashboard role

Extensions have a userContext prop that’s populated with information about the active Dashboard user. This object has a roles field, which is an array of RoleDefinition objects for each role that the active user is attributed to.

A role definition has these fields:

Field name
Type
Example
type
‘builtIn’ | ‘custom’
builtIn
Specifies the role type. Custom roles are only available to private apps.
name
string
Developer
The name of the user role.

The name field provides the name of the user role, and you can use it to modify the functionality of your UI Extension.

Custom user roles (private apps only)

Each role definition has a type field, which specifies the role type. The type field can either be ‘builtIn’ or ‘custom’. Because custom roles are specific to a given account, these roles are only available for private apps.

Tailoring content based on the Dashboard role

A common use of this information is to conditionally display content based on the user role. Below is an example app that shows content tailored to particular user roles.

import { Badge, Box, Inline, ContextView } from "@stripe/ui-extension-sdk/ui"; import type { ExtensionContextValue } from "@stripe/ui-extension-sdk/context"; const App = ({ userContext }: ExtensionContextValue) => { const isAdmin = userContext?.roles?.some(role => role.name === 'Administrator'); const isDeveloper = !isAdmin && userContext?.roles?.some(role => role.name === 'Developer'); const isaAnotherRole = !isDeveloper && !isAdmin; return ( <ContextView title="Role based access" > <Box> <Box css={{ paddingBottom: 'large'}}>Active user roles: {userContext?.roles?.map(role => <Badge key={role.name}>{role.name}</Badge>)}</Box> { isAdmin && (<Box>Only <Inline css={{ fontWeight: 'semibold' }}>admin</Inline> users can see this message.</Box>) } { isDeveloper && (<Box>Only <Inline css={{ fontWeight: 'semibold' }}>developers</Inline> users can see this message.</Box>) } { isaAnotherRole && (<Box>Only users who are not admins or developers can see this message.</Box>) } </Box> </ContextView> ); }; export default App;
A screenshot of the result of the example code above for an Administrator user

The result of the example app when viewing the app as an Administrator user

See also

  • Build a UI
  • Extension SDK API reference
  • User roles
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc