Account Management API Overview · Account Management

note

Account Management API is now deprecated and we recommend that you use Account Management functionality built into Elastic Path Commerce 8.2 and later.

Account Management API resources model the fundamental aspects of B2B ecommerce with each resource encapsulating a single part of the B2B ecommerce process. For example, Account Management API has resources for:

Workflow

Resources are linked together with other related resources into workflows that can be used to perform an action. For example, the workflow to create a new associate for a buyer organization involves retrieving the organization, and then following the associates link to the associateform. Then “associateform” is used to create a new associate for that specific organization. By following these workflows, you can perform actions such as add an organization, add a division, perform a search and so on.

Authentication

The Account Management API uses the OpenID Connect protocol for authentication. To authenticate to the Account Management API, the client must obtain an access token to be included in the HTTP request headers. For authorization to the Account Management API, a client is required to be authorized through OpenID Connect authentication, specifically the Authorization Code Flow. For more information about the Authorization Code Flow and OpenID Connect, see:

OpenID Connect Basic Client Implementer’s Guide

OpenID configuration

You must configure an identity provider to use with Account Management, such as: - Okta - Keycloak

Authorization by access token

Authorization involves the client, an OpenID provider and the Account Management API. The client will handle several requests to obtain an access token that will be used to authorize the client to the Account Management API.

The client retrieves the OpenID Discovery document from https://<ACCOUNT-MANAGEMENT-API>/admin/.well-known/openid-configuration. This document includes the standard OpenID Provider Metadata and following additional values required for the authorization request:

value	Description
`account_management_client_id`	The Client ID that must be used in the authorization request.
`account_management_required_scopes`	The scopes that must be requested in the authorization request.
`account_management_oidc_discovery_url`	The original location of the discovery document.

The client redirects the user to the OpenID Connect provider, initiating a request following the steps to prepare the authentication request, using the parameters in the discovery document.
The user is authenticated with the OpenID Connect provider.
The user is redirected to the client with the authorization code in the URL.
The client passes this authorization code to the Account Management API, https://<ACCOUNT-MANAGEMENT-API>/admin/oauth2/tokens.
The Account Management API provides an access token that can be used in the HTTP Authorization request header in all subsequent requests.

For more information on implementing OpenID Connect for the OAuth 2.0 protocol, see the OpenID Connect Basic Client Implementer’s Guide.

Adding the access token to request headers

The OAuth 2.0 access token returned from the previous series of requests is a bearer token that is used with requests from the client to the Account Management API. The bearer token should be added to the HTTP request headers when making requests to the Account Management API Service. The following code is an example:

Authorization: Bearer AbCdEf123456

Deleting the access token

The OAuth 2.0 token will be valid until it expires or is deleted. The following code is an example to delete the token:

curl 'https://<ACCOUNT-MANAGEMENT-API>/admin/oauth2/tokens' -X DELETE -H 'authorization: bearer AbCdEf123456'

Static API access key

You can use the API_ACCESS_TOKEN environment variable as a static API access key to authenticate as a seller administrator in the Account Management service. The token must contain atleast 32 characters. To use this token, pass the token as a bearer token to the authorization request header. The following code is an example:

Authorization: Bearer <API_ACCESS_TOKEN>

Events API

The Account Management events API sends JMS (Java Messaging System) events when you create, update, or delete the following resources:

Associates or users
User account assignment or user account role assignments
Accounts

Associates or users

The following code is an example message for USER_CREATED event:

{
   "eventType":{
      "ordinal":0,
      "name":"USER_CREATED"
   },
   "data":{
      "guid":"5f9a7e6d-bfc3-48ec-a5a4-d2f22a09831a",
      "name":"Buyer Admin",
      "email":"email4@email4.com",
      "type":"ASSOCIATE",
      "oidcSubject":null,
      "oidcIssuer":null
   }
}

The following code is an example message for USER_UPDATED event:

{
   "eventType":{
      "ordinal":1,
      "name":"USER_UPDATED"
   },
   "data":{
      "guid":"ffffffff-000f-000f-000f-000f0000000f",
      "name":"Buyer Admin",
      "email":"buyer.admin@elasticpath.com",
      "type":"ASSOCIATE",
      "oidcSubject":"006e4d6a-9107-452b-aa41-d93cdba88930",
      "oidcIssuer":"http://localhost:8181/auth/realms/Commerce"
   }
}

User account assignment or user account role assignments

The user account assignment or user account role assignments triggers the same event. The following code is an example message for USER_ACCOUNT_ROLE_ASSIGNMENT_CREATED event:

{
   "eventType":{
      "ordinal":2,
      "name":"USER_ACCOUNT_ROLE_ASSIGNMENT_CREATED"
   },
   "data":{
      "accountGuid":"eeeeeeee-000e-000e-000e-000e0000000e",
      "userGuid":"5f9a7e6d-bfc3-48ec-a5a4-d2f22a09831a",
      "roles":[
         "BUYER"
      ]
   }
}

The following code is an example message for USER_ACCOUNT_ROLE_ASSIGNMENT_UPDATED event:

{
   "eventType":{
      "ordinal":3,
      "name":"USER_ACCOUNT_ROLE_ASSIGNMENT_UPDATED"
   },
   "data":{
      "accountGuid":"eeeeeeee-000e-000e-000e-000e0000000e",
      "userGuid":"5f9a7e6d-bfc3-48ec-a5a4-d2f22a09831a",
      "roles":[
         "BUYER"
      ]
   }
}

The following code is an example message for USER_ACCOUNT_ASSIGNMENT_DELETED event:

{
   "eventType":{
      "ordinal":4,
      "name":"USER_ACCOUNT_ASSIGNMENT_DELETED"
   },
   "data":{
      "accountGuid":"eeeeeeee-000e-000e-000e-000e0000000e",
      "userGuid":"5f9a7e6d-bfc3-48ec-a5a4-d2f22a09831a"
   }
}

Accounts

The following code is an example for account creation message:

{
   "eventType":{
      "ordinal":5,
      "name":"ACCOUNT_CREATED"
   },
   "data":{
      "name":"added-account-1",
      "guid":"5d5ef6b3-030a-42db-b47d-15ae9e2d0419",
      "legalName":"Test Company",
      "registrationId":"example-registration-id",
      "externalId":"example-externalid",
      "status":"DISABLED",
      "parentAccountGuid":"bbbbbbbb-000b-000b-000b-000b0000000b"
   }
}

The following code is an example for account update message:

{
   "eventType":{
      "ordinal":6,
      "name":"ACCOUNT_UPDATED"
   },
   "data":{
      "name":"added-account-1",
      "guid":"5d5ef6b3-030a-42db-b47d-15ae9e2d0419",
      "legalName":"Test Company",
      "registrationId":"example-registration-id",
      "externalId":"example-externalid",
      "status":"DISABLED",
      "parentAccountGuid":"bbbbbbbb-000b-000b-000b-000b0000000b"
   }
}