Users and authentication in Sharetribe
This article explains how users are managed and how authentication and authorization works in Sharetribe.
Table of Contents
- User roles in Sharetribe
- Transaction related roles: operator and system
- User access
- Registered marketplace users
- Login as user
- Integration API
- Authenticating to Sharetribe APIs
- Banned and deleted users
- Banned user
- Deleted user
- Authentication in Sharetribe
- Anonymous access to Marketplace API
- User access to Marketplace API
- Trusted access to Marketplace API
- Full access to Integration API
Anyone who registers to your Sharetribe marketplace is referred to as a user. In addition, the operator can take certain actions on the marketplace even though they are not technically a user there. Sharetribe marketplaces only facilitate transactions between registered users – in other words, it is not possible for someone to purchase or book a listing without signing up as a user.
Sharetribe has two possible roles for a registered user: customer and provider. All users can be both customers and providers by default. This means that even if a person has created a listing, which means they can be a provider, they can also be a customer on someone else's listing.
If you want to limit certain users to only customers or only providers, you will need to create those limitations in your client application. You can use extended data to determine that a user is in a certain group, and then allow a subset of your marketplace functionalities, e.g. listing creation, for a specified group.
In a transaction, a customer is the user who purchases or books the listing. In marketplaces with payments, the customer is the user who pays the listing price. Customers can save their payment details in Sharetribe.
Customers need to enter a valid email address to sign up to Sharetribe, but other than that customers are not required to enter further information to use the marketplace. When using the Stripe default payment integration, customers can save a payment method, however the payment method information is saved in Stripe and not directly in Sharetribe.
Within a transaction, customers can initiate or transition transactions specified for the customer.
When a user creates a listing and someone else books or purchases that listing, the user becomes the provider of the transaction in question. In marketplaces with payments, the provider is the transaction party who receives the listing price.
This means that if the payment happens within the marketplace, the provider will need to verify their identity to the payment gateway to adhere to the payment processor's Know Your Customer requirements.
Within a transaction, providers can initiate or transition transactions specified for the provider.
A marketplace operator is not a user in the marketplace – they cannot sign in to the marketplace with the same credentials they use to sign in to Sharetribe Console. The operator can, however, take actions on the marketplace through Sharetribe Console or Integration API, when those actions are defined for the operator. Operators cannot participate in the messaging between customer and provider within the transaction.
A transaction transition is performed by the system if it is scheduled to happen automatically.
Sharetribe marketplace listings can be viewed by anyone by default, whether they are registered users or not. If a user wants to start a transaction or create a listing, they need to be registered to Sharetribe.
Listings can only be updated by their author, i.e. the registered user who originally created the listing. Operators can create listings for a registered user, and update existing listings.
Beyond that, Sharetribe does not have different levels of user access within the marketplace. Operators who want to create more complex user hierarchies will need to think about the levels of user access they want each custom role to have, and potentially use a custom backend solution to complement Sharetribe default user management. If you are contemplating creating a user hierarchy in your Sharetribe marketplace, contact Sharetribe Support and let us know your use case – we're happy to help you figure out a suitable solution!
Sharetribe has a feature through which operators can log in to their marketplace as a registered user and take limited actions on their behalf. When using the Login as user feature, operators cannot initiate or transition transactions or modify the user's payout information. However, they can e.g. create and update listings on behalf of the user. The login as user feature can be accessed through the Sharetribe Console, by navigating to a user profile and clicking on the three dots next to the profile image of the user.
Sharetribe Integration API allows trusted secure applications to access all data within a marketplace. It is not accessible for marketplace users with their own sign-in credentials. Instead, Integration API can be used to create server-side integrations to external systems, or to retrieve data for custom marketplace dashboards.
Sharetribe marketplace users need to sign up with their email address to create listings and participate in transactions. Alternatively, they can use social logins to sign up, or to login with an email address that already has a user within Sharetribe.
When a user is banned or deleted, they can no longer take action on the marketplace.
Banning a user means removing the user and all of the user’s listings from a marketplace due to inappropriate behaviour. The email with which a banned user registered to the marketplace can not be used to create new accounts. The user data is only visible when it is linked to, and even then only ID and banned status are shown.
Operators can ban and unban users through Sharetribe Console, but there is no endpoint in the Sharetribe APIs to ban a user. Unbanning a user does not automatically reinstate the user's deleted listings.
Deleting a user means completely and irreversibly removing all of the user's personal data. This includes all of the public-facing data like profile and listings as well as the user account information.
Operators can delete users through Sharetribe Console. In addition, there is an endpoint in Marketplace API so that operators can build a functionality for users to delete their own accounts. We have a how-to guide on implementing a Delete user feature.
The Sharetribe APIs limit visibility to certain data based on the authentication level of the user. Marketplace API has three different levels of access, whereas Integration API only has full access or no access. This means that when using any Integration API endpoints, it is crucial to only use them from a secure context i.e. from server code, never from browser code.
Some endpoints can be accessed without signing in to Sharetribe. These include viewing published listings, bookings and reviews, as well as public user data.
In addition, the user creation endpoints and password reset request
endpoint can be called with an anonymous access token. Password reset
endpoint requires a
passwordResetToken that is sent as a response to
the password reset request command, and the token is sent directly to
the email specified in the request.
Only authenticated users can access endpoints that deal with updating user information, creating and updating listings, and initiating and transitioning transactions.
Through initiating and transitioning transactions, authenticated users have access to functionalities that do not have specific endpoints. For instance creating and accepting bookings and reviewing transaction counterparties are actions that can only happen within the context of a transaction process.
Some transitions within a transaction process can include privileged actions that require a trusted context i.e. they are privileged transitions. Privileged actions include setting the transaction line items and updating the transaction metadata.
These transitions require a trusted token or a trusted SDK method, both of which are obtained using the Sharetribe application client secret. In practice, the trusted context is a server environment. With the Sharetribe Web Template, the client application server has default implementations of trusted endpoints for initiating and transitioning transactions.
The Integration API offers access to the entire marketplace data. This includes all users, listings, transactions, and messages. To see what endpoints you can access using the Integration API, refer to the Integration API reference.
To access the Integration API you need a valid access token obtained through the Authentication API or the Sharetribe Integration SDK. You should only grant access to trusted applications, such as ones that run in your own backend systems, or applications that can only be executed by authorized marketplace operators.
In order to gain authorisation, you need to authenticate using the client ID and client secret of your Integration API application. Read more on how to authenticate in the Authentication API reference.