Logging In as Company User

In the B2B context, buyers typically represent a company and act on its behalf. For this reason, Spryker Commerce OS provides the Company Account capability which allows companies to create multiple Company Users, as well as organize them in Business Units depending on the user role and scope. Customers can impersonate as various Company Accounts depending on the task they need to perform.

To impersonate a customer as a Company User, API clients can use the Business on Behalf API. It provides REST access to retrieve a list of the Company Users available to the currently logged in user and impersonate as any user available to them.

Authentication
Before impersonating as Company Users, customers need to authenticate first. For details on how to do so, see Authentication and Authorization.

During the impersonation process, customers receive an Access Token. The token can be used to access any B2B REST API resources, such as Companies, Business UnitsCarts etc. Also, authenticated company users will benefit from the merchant-specific prices available to them (applied to certain business units as a rule) instead of the default ones. Also, you can customize the behavior of your API client to match the user's company, job role, business unit, and scope.

If the Prices per Merchant Relation (Customer specific prices) feature is enabled in your project, all prices returned by Spryker REST API are the prices specific to the Company of the current Company User (if any).

The same as with B2C resource access tokens, the tokens provided by the API have limited timeframe. When receiving an access token, the response body contains not only the access token itself, but also its lifetime, in seconds, and a Refresh Token. When the lifetime expires, the Refresh Token can be exchanged for a new Access Token. The new token will also have a limited lifetime and have a corresponding Refresh Token for future authentication. The default lifetime of the tokens is 8 hours (28800 seconds) for an access token and 1 month (2628000 seconds) for a refresh token. The settings can be changed in the module configuration.

For details, see Authentication and Authorization.

In your development, the endpoint can help you to:

  • Authenticate users as B2B Company Users;
  • Obtain a token that can be used when accessing protected B2B resources;
  • Provide customized user experience based on the user's Company, Business Unit, Role etc;
  • Allow users to benefit from prices specific to their company.

Installation

For detailed information on the modules that provide the API functionality and related installation instructions, see Company Account Feature Integration.

Retrieving Available Company Users

To retrieve a list of all the Company Users available to the currently logged in user, send a GET request to the following endpoint:

/company-users/mine

Sample request: GET http://glue.mysprykershop.com/company-users/mine

Authentication Required
To get a list of Company Users, you need to authenticate first and pass an access token as a part of your request. For details, see Authentication and Authorization.

Response

The endpoint responds with a RestCompanyUserCollectionResponse that contains the Company Users available to the currently logged in user.

Response Attributes:

Attribute* Type Description
id String

Specifies the Company User ID.

You can use the ID to impersonate as the Company User via the /company-user-access-tokens endpoint.

isActive Boolean Indicates whether the Company User is active.
isDefault Boolean Indicates whether the Company User is the default one for the logged in customer.

*The attributes mentioned are all attributes in the response. Type is not mentioned.

If the currently logged in user does not have access to any Company User accounts, the endpoint returns an empty RestCompanyUserCollectionResponse response.

To help customers with selecting the necessary Company User, you can provide additional information, such as the company and business unit that each account belongs to. Also, you can identify which roles the corporate accounts can perform within the company. To fetch such information, extend the response of the endpoint with the companies and company-business-units, and company-roles resource relationships.

Sample request: GET http://glue.mysprykershop.com/company-users/min?include=companies,company-business-units,company-roles

In this case, the following additional attributes will be added to the response:

Resource Attribute* Type Description
companies name String Specifies the name of the Company.

isActive

Boolean Indicates whether the Company is active.
status String Specifies the status of the Company. Possible values: Pending,Approved or Denied.
company-roles name String Specifies the name of the Company Role.
isDefault Boolean Indicates whether the Company Role is the default role for the company.
company-business-units name String Specifies the name of the Business Unit.
email String Specifies the email address of the Business Unit.
phone String Specifies the telephone number of the Business Unit.
externalUrl String Specifies the url of the website of the Business Unit.
bic String Specifies the Bank Identifier Code of the Business Unit.
iban String Specifies the International Bank Account Number of the Business Unit.
defaultBillingAddress String Specifies the default billing address of the Business Unit.

*The attributes mentioned are all attributes in the response. Type and ID are not mentioned.

Possible Errors

Code Reason
401 The access token is invalid.
403 The access token is missing.

Impersonating as a Company User

To impersonate a user as a Company Account and receive a B2B access token, send a POST request to the following endpoint:

/company-user-access-tokens

Sample request: POST http://glue.mysprykershop.com/company-user-access-tokens

Authentication Required
To access the endpoint, you need to authenticate customers as regular users first and pass an access token as a part of your request. For details, see Authentication and Authorization.

Attributes:

Attribute Type Description
idCompanyUser String Specifies the ID of the Company User to impersonate.

Company User IDs can be retrieved using the /company-users/mine endpoint.

Sample Request:

{
    "data": {
        "type": "company-user-access-tokens",
        "attributes": {
            "idCompanyUser": "5daf27b3-eddf-5b81-98cb-899f140f97e5"
        }
    }
}

Response

If the request was successful, the endpoint responds with a RestCompanyUserAccessTokensRequest containing the access and refresh tokens.

Response Attributes:

Attribute* Type Description
tokenType String Specifies the token type. By default, the type is always Bearer.
accessToken String Specifies the access token that can be used to impersonate as the Company User.
expiresIn Integer Specifies the time period after which the access token expires (in seconds). By default, 28800.
refreshToken String Specifies the refresh token that can be exchanged for a new access token after the current one expires.

*The attributes mentioned are all attributes in the response. Type and ID are not mentioned.

Possible Errors

Code Reason
401

Failed to authenticate a user. This can happen due to the following reasons:

  • the currently logged on user cannot authenticate as the specified Company User;
  • the specified Company User does not exist;
  • the access token provided in the request is incorrect.
403 The access token is missing in the request.
422 The Company User Id format is incorrect.

Accessing B2B Resources

After impersonating as a Company User, you can access the resources provided to B2B customers using the access token received via the /company-user-access-tokens endpoint. When accessing the resources, you need to pass the token in the Authorization header. For details, see Accessing Resources.

Refreshing the Access Token

You can refresh an access token issued for a Company User the same as any other access token issued by Glue API. For details, see Refreshing Tokens.

See also:

 

Last review date: July 12, 2019