Identity (1.0.0)

Download OpenAPI specification:Download

The fabric Identity API lets you manage users. You can create and update user names and addresses. Users can log in to an application and can change or reset their passwords.

User

The User endpoints let you create local or guest users, update a user's user name, and get information about a specific user.

Get user

Get user details

SecurityBearerAuth
Request
path Parameters
userId
required
string

User ID

Example: 6169b2d892a5f30009d76480
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Responses
200

OK

404

User not found

500

Internal Server Error

get/api-commerceIdentity/user/{userId}
Response samples
application/json
{
  • "isActive": true,
  • "registrationDate": "2020-04-15T10:08:04.246Z",
  • "expiryDate": "2020-04-15T10:08:04.246Z",
  • "roles": "customer",
  • "name": {
    },
  • "phone": [
    ],
  • "email": "test@mail.com",
  • "extra": { },
  • "registrationSite": "XXX",
  • "account": "xxxxxcxxxxxxxxxxxxxx",
  • "userId": "6169b2d892a5f30009d76480",
  • "address": [
    ],
  • "provider": [
    ],
  • "createdAt": "2020-04-15T10:08:04.246Z",
  • "updatedAt": "2020-04-15T10:08:04.246Z"
}

Update user name

Update a user's login user name

SecurityApiKeyAuth or BearerAuth
Request
path Parameters
userId
required
string

User ID

Example: 6169b2d892a5f30009d76480
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Request Body schema: application/json
oldUsername
required
string [ 5 .. 40 ] characters

Old user name

newUsername
required
string [ 5 .. 40 ] characters

New user name

Responses
200

OK

404

User not found

500

Internal Server Error

patch/api-commerceIdentity/user/{userId}/username
Request samples
application/json
{
  • "oldUsername": "user101",
  • "newUsername": "user202"
}
Response samples
application/json
{
  • "isActive": true,
  • "registrationDate": "2020-04-15T10:08:04.246Z",
  • "expiryDate": "2020-04-15T10:08:04.246Z",
  • "roles": "customer",
  • "name": {
    },
  • "phone": [
    ],
  • "email": "test@mail.com",
  • "extra": { },
  • "registrationSite": "XXX",
  • "account": "xxxxxcxxxxxxxxxxxxxx",
  • "userId": "6169b2d892a5f30009d76480",
  • "address": [
    ],
  • "provider": [
    ],
  • "createdAt": "2020-04-15T10:08:04.246Z",
  • "updatedAt": "2020-04-15T10:08:04.246Z"
}

Create local user

Create local user

SecurityApiKeyAuth
Request
header Parameters
object (xSiteContextCreate)

JSON object containing channel, account, stage, date, and site

Request Body schema: application/json
object (BaseUser)

User details

object
Responses
200

Sign-in response

400

Bad request

500

Internal Server Error

post/api-commerceIdentity/user/local
Request samples
application/json
{
  • "user": {
    },
  • "provider": {
    }
}
Response samples
application/json
{
  • "_id": "596f7557696e2d4d617a616c546f7621",
  • "userId": "6169b2d892a5f30009d76480",
  • "roles": "customer",
  • "name": "Pat E Kake",
  • "account": "xxxxxcxxxxxxxxxxxxxx",
  • "userType": "customer",
  • "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4...",
  • "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4..."
}

Create guest user

Create guest user

SecurityApiKeyAuth
Request
header Parameters
object (xSiteContextCreate)

JSON object containing channel, account, stage, date, and site

Request Body schema: application/json
object (BaseUser)

User details

object
Responses
200

Sign-in response

400

Bad request

500

Internal Server Error

post/api-commerceIdentity/user/guest
Request samples
application/json
{
  • "user": {
    },
  • "provider": {
    }
}
Response samples
application/json
{
  • "_id": "596f7557696e2d4d617a616c546f7621",
  • "userId": "6169b2d892a5f30009d76480",
  • "roles": "customer",
  • "name": "Pat E Kake",
  • "account": "xxxxxcxxxxxxxxxxxxxx",
  • "userType": "customer",
  • "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4...",
  • "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4..."
}

Address

The Address endpoints let you create, delete, and update addresses, as well as get a list of addresses or address information.

List user's addresses

List all addresses for specified user

SecurityApiKeyAuth or BearerAuth
Request
path Parameters
userId
required
string

User ID

Example: 6169b2d892a5f30009d76480
query Parameters
kind
string

Type of user to return

Example: kind=customer
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Responses
200

OK

404

No addresses found

500

Internal Server Error

get/api-commerceIdentity/user/{userId}/address
Response samples
application/json
[
  • {
    }
]

Create user address

Create address for specified user

SecurityApiKeyAuth or BearerAuth
Request
path Parameters
userId
required
string

User ID

Example: 6169b2d892a5f30009d76480
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Request Body schema: application/json
attention
string

Address recipient

address1
required
string

Primary address

address2
string

Second address line

address3
string

Third address line

city
required
string

Address city

state
required
string

Address state

country
required
string

Address country

zipCode
required
string

Address zip code

company
string

Company name

kind
string

Address type

object

Telephone number and type associated with address

object
email
string

Email address

Responses
200

OK

400

Bad request

500

Internal Server Error

post/api-commerceIdentity/user/{userId}/address
Request samples
application/json
{
  • "attention": "Account Manager",
  • "address1": "1234 Main St.",
  • "address2": "Suite 710",
  • "address3": "Floor 7",
  • "city": "Houston",
  • "state": "TX",
  • "country": "USA",
  • "zipCode": 77035,
  • "company": "Acme Inc.",
  • "kind": "Business",
  • "phone": {
    },
  • "name": {
    },
  • "email": "test@mail.com"
}
Response samples
application/json
[
  • {
    }
]

Get specific address

Get specified address for specified user

SecurityApiKeyAuth or BearerAuth
Request
path Parameters
userId
required
string

User ID

Example: 6169b2d892a5f30009d76480
addressId
required
string

Address ID

Example: 858265qt314159
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Responses
200

OK

404

Address not found

500

Internal Server Error

get/api-commerceIdentity/user/{userId}/address/{addressId}
Response samples
application/json
[
  • {
    }
]

Update specific address

Update specified address for specified user

SecurityApiKeyAuth or BearerAuth
Request
path Parameters
userId
required
string

User ID

Example: 6169b2d892a5f30009d76480
addressId
required
string

Address ID

Example: 858265qt314159
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Request Body schema: application/json
attention
string

Address recipient

address1
required
string

Primary address

address2
string

Second address line

address3
string

Third address line

city
required
string

Address city

state
required
string

Address state

country
required
string

Address country

zipCode
required
string

Address zip code

company
string

Company name

kind
string

Address type

object

Telephone number and type associated with address

object
email
string

Email address

Responses
200

OK

404

Address not found

500

Internal Server Error

put/api-commerceIdentity/user/{userId}/address/{addressId}
Request samples
application/json
{
  • "attention": "Account Manager",
  • "address1": "1234 Main St.",
  • "address2": "Suite 710",
  • "address3": "Floor 7",
  • "city": "Houston",
  • "state": "TX",
  • "country": "USA",
  • "zipCode": 77035,
  • "company": "Acme Inc.",
  • "kind": "Business",
  • "phone": {
    },
  • "name": {
    },
  • "email": "test@mail.com"
}
Response samples
application/json
[
  • {
    }
]

Delete specific address

Delete specified address for specified user

SecurityApiKeyAuth or BearerAuth
Request
path Parameters
userId
required
string

User ID

Example: 6169b2d892a5f30009d76480
addressId
required
string

Address ID

Example: 858265qt314159
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Responses
200

OK

404

Address not found

500

Internal Server Error

delete/api-commerceIdentity/user/{userId}/address/{addressId}
Response samples
application/json
[
  • {
    }
]

Set default address

Set default address for specified user

SecurityApiKeyAuth or BearerAuth
Request
path Parameters
userId
required
string

User ID

Example: 6169b2d892a5f30009d76480
addressId
required
string

Address ID

Example: 2468qt3414159
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Responses
200

OK

404

Address not found

500

Internal Server Error

post/api-commerceIdentity/user/{userId}/address/{addressId}/set
Response samples
application/json
[
  • {
    }
]

Unset default address

Unset default address for specified user

SecurityApiKeyAuth or BearerAuth
Request
path Parameters
userId
required
string

User ID

Example: 6169b2d892a5f30009d76480
addressId
required
string

Address ID

Example: 2468qt3414159
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Responses
200

OK

404

Address not found

500

Internal Server Error

post/api-commerceIdentity/user/{userId}/address/{addressId}/unset
Response samples
application/json
[
  • {
    }
]

Auth

The Auth endpoints let the user log in and change or reset a password. You can also refresh a local user.

Log in local user

Log in local user with password

SecurityApiKeyAuth
Request
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Request Body schema: application/json
username
required
string

User name

password
required
string

login password

Responses
200

Sign-in response

400

Local authentication failed

401

Authentication Failed

post/api-commerceIdentity/auth/local/login
Request samples
application/json
{
  • "username": "user101",
  • "password": "ABC123"
}
Response samples
application/json
{
  • "_id": "596f7557696e2d4d617a616c546f7621",
  • "userId": "6169b2d892a5f30009d76480",
  • "roles": "customer",
  • "name": "Pat E Kake",
  • "account": "xxxxxcxxxxxxxxxxxxxx",
  • "userType": "customer",
  • "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4...",
  • "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4..."
}

Refresh local user

Refresh local user with refresh token

SecurityApiKeyAuth
Request
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Request Body schema: application/json
refreshToken
required
string

Refresh token

Responses
200

Sign-in response

400

Local authentication failed

401

Authentication Failed

post/api-commerceIdentity/auth/local/refresh
Request samples
application/json
{
  • "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4..."
}
Response samples
application/json
{
  • "_id": "596f7557696e2d4d617a616c546f7621",
  • "userId": "6169b2d892a5f30009d76480",
  • "roles": "customer",
  • "name": "Pat E Kake",
  • "account": "xxxxxcxxxxxxxxxxxxxx",
  • "userType": "customer",
  • "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4...",
  • "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4..."
}

Reset password

Reset password for specified user

SecurityApiKeyAuth or BearerAuth
Request
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Request Body schema: application/json
username
required
string

User name

Responses
200

OK

401

Inactive user

404

User not found

500

Internal Server Error

patch/api-commerceIdentity/auth/local/reset
Request samples
application/json
{
  • "username": "user101"
}
Response samples
application/json
{
  • "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4...",
  • "kind": "RESET_PASSWORD",
  • "expiresAt": "2020-04-15T10:08:04.246Z",
  • "isRedeemed": true,
  • "userId": "6169b2d892a5f30009d76480",
  • "name": {
    },
  • "email": "test@mail.com"
}

Update password

Update user password
Note: This endpoint is called internally by the "change password" endpoint

SecurityApiKeyAuth or BearerAuth
Request
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Request Body schema: application/json
userId
string

User ID

resetToken
string

Reset token

newPassword
string

New password

Responses
200

OK

401

Token expired

404

Token not found

500

Internal Server Error

patch/api-commerceIdentity/auth/password
Request samples
application/json
{
  • "userId": "6169b2d892a5f30009d76480",
  • "resetToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4...",
  • "newPassword": "ABC123"
}
Response samples
application/json
{
  • "isActive": true,
  • "registrationDate": "2020-04-15T10:08:04.246Z",
  • "expiryDate": "2020-04-15T10:08:04.246Z",
  • "roles": "customer",
  • "name": {
    },
  • "phone": [
    ],
  • "email": "test@mail.com",
  • "extra": { },
  • "registrationSite": "XXX",
  • "account": "xxxxxcxxxxxxxxxxxxxx",
  • "userId": "6169b2d892a5f30009d76480",
  • "address": [
    ],
  • "provider": [
    ],
  • "createdAt": "2020-04-15T10:08:04.246Z",
  • "updatedAt": "2020-04-15T10:08:04.246Z"
}

Change password

Change password for signed-in user
Note: Use this endpoint to change a user's password

SecurityApiKeyAuth or BearerAuth
Request
header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Request Body schema: application/json
userId
string

User ID

resetToken
string

Access token

newPassword
string

New password

Responses
200

OK

401

Incorrect password

500

Internal Server Error

patch/api-commerceIdentity/auth/change-password
Request samples
application/json
{
  • "userId": "6169b2d892a5f30009d76480",
  • "resetToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxZjIyMTU4...",
  • "newPassword": "ABC123"
}
Response samples
application/json
{
  • "isActive": true,
  • "registrationDate": "2020-04-15T10:08:04.246Z",
  • "expiryDate": "2020-04-15T10:08:04.246Z",
  • "roles": "customer",
  • "name": {
    },
  • "phone": [
    ],
  • "email": "test@mail.com",
  • "extra": { },
  • "registrationSite": "XXX",
  • "account": "xxxxxcxxxxxxxxxxxxxx",
  • "userId": "6169b2d892a5f30009d76480",
  • "address": [
    ],
  • "provider": [
    ],
  • "createdAt": "2020-04-15T10:08:04.246Z",
  • "updatedAt": "2020-04-15T10:08:04.246Z"
}

Verify reset token

Verify password reset token

Request
path Parameters
token
required
string

Password reset token

header Parameters
object (xSiteContext)

JSON object containing channel, account, stage, and date

Responses
200

OK

401

Token expired

404

Token not found

get/api-commerceIdentity/auth/token/{token}
Response samples
application/json
{
  • "tokenValid": true,
  • "userId": "6169b2d892a5f30009d76480"
}