Identity APIs (2.0.0)

Download OpenAPI specification:Download

fabric Identity APIs to be used by all 3rd party developers to authenticate and obtain access tokens for building commerce applications that integrate with fabric APIs (like OMS, Offers etc.). Additionally user self service APIs are provided for userapp(s) developers to quickly build support for typical identity account operations like get/update login information, change password and forgot password flows.

Authentication APIs

These APIs allow sysapp and userapp to authenticate themselves or their end users with fabric Identity. The objective of these APIs is to return an access token to apps, which can then be used to invoke other fabric APIs (like OMS, PIM etc).

Authorize `userapp` with and without PKCE

Use this API to authenticate userapp(s) with fabric Identity. This API is not needed for sysapp authentication (see the /token API instead). The immediate response of this operation would be a browser re-direct to the hosted login page configured in fabric Identity. Once the end user is authenticated on the hosted login page, fabric Identity will perform a redirect back to the userapp on the provided redirect_uri. This API can be used for both authroization code flow with and without PKCE.

Request
query Parameters
client_id
required
string

Client ID of the userapp

response_type
required
string

The type of the response expected. This should always be set to code (as per OAuth 2.0 grant type , refer https://datatracker.ietf.org/doc/html/rfc6749#page-19)

scope
required
string

The scope of the API call. This should always be set to openid (as per OpenID Connect standard - https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)

redirect_uri
required
string

The redirect uri of the userapp that fabric Identity would redirect the user once the login is successful. This uri should be hosted by userapp and as part of the redirect would receive the auth code (as code query paramter) which can then be exchanged for the access token (see /token).

state
required
string

A random string created by userapp used to maintain state between the request and the callback. This helps mitigate CSRF when it is cryptographically derived from a browser cookie denoting the user/session.

code_challenge_method
string

Required only when using authorization code flow with PKCE. A code challenge method supported by PKCE specification. fabric Identity only supports the value of S256 (for more information - https://datatracker.ietf.org/doc/html/rfc7636#section-4.2). This parameter is mandatory for authorization code flow with PKCE and is not required for the regular authorization code flow.

code_challenge
required
string

Required only when using authorization code flow with PKCE. The code challenge created by the userapp as per the specification on PKCE - https://datatracker.ietf.org/doc/html/rfc7636#section-4.2.

Responses
302

Found. A successful response to this API would re-direct the user to the hosted login page provided by the fabric Identity. Once the user successfully logs in, fabric Identity would re-direct the client back to the redirect_uri hosted on the userapp with the authorization code (as query parameter code) and the state (as query parameter state). The `state`` parameter in the callback would be the same value as sent in the request.

get/oauth2/default/v1/authorize

Fetch access token

This API allows userapp and sysapp to fetch the access tokens. For userapp use this API after the /authorize API and the subsequent callback. For userapp this endpoint supports generation of access token from authorization code or from refresh token, sent in the previous authorize endpoint's callback. For sysapp this API can directly be used to get an access token, no prior /authorize end point call is needed.

Request
path Parameters
authServerId
required
string

Use default for userapp flows. For sysapp, use the tenant specific server id provided by fabric Identity (see Getting Started).

header Parameters
Authorization
string

Required for userapp with authorization code flow without PKCE and for sysapp. Basic authorization header to be created using the client id and client secret of the userapp or sysapp. The value should be derived as Basic base64encode(client_id:client_secret). Refer https://datatracker.ietf.org/doc/html/rfc2617#section-2 for more details.

Request Body schema: application/x-www-form-urlencoded
client_id
string

Required only for userapp and authorization code flow with PKCE. Client ID of the userapp.

redirect_uri
string

Required for userapp with both authorization code flow with and without PKCE. URL encoded redirect_uri sent by the userapp in the previous /authorize call.

grant_type
required
string

Required for all authentication flows and app types. Set to authorization_code for userapp (for both authorization code flow with and without PKCE). Set to client_credentials when using for sysapp.

Enum: "authorization_code" "client_credentials"
code_verifier
string

Required only for userapp and authorization code flow with PKCE. Code verifier using for deriving the code_challenge sent in the /authorize call. Refer to https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 for more details

code
string

Required for userapp with both authorization code flow with and without PKCE. Authorization code received as part of the callback response to the /authorize call.

scope
string

Required only for sysapp. Value should always be set to s2s.

Responses
200

Access token response

post/oauth2/{authServerId}/v1/token
Response samples
application/json
{
  • "token_type": "string",
  • "expires_in": 0,
  • "access_token": "string",
  • "id_token": "string",
  • "scope": "string"
}

User Self Service APIs

These APIs allow userapp(s) to provide user self service for their identity accounts. These include basic user services like get/update login information, change password and forgot password flows.

Get user details

This API allows a logged in user to get his own details from the fabric Identity. The API is designed to return the details of the user whose bearer token is sent in the header.

Request
header Parameters
Authorization
required
string

Bearer token of the login in user

Example: Bearer <access token of the user>
Responses
200

User Identity Object

403

User is not allowed to perform the action

500

The request was received but an internal error occurred

get/users/self
Response samples
application/json
{
  • "id": "1234-1234-1234",
  • "status": "active",
  • "isStaffUserFederated": true,
  • "loginId": "sdsdf232ew-123asdaa-1231231",
  • "orgId": "123123-23wdd-123234",
  • "email": "test.user@foobar.com",
  • "primarycontact": "+1 650 333 4444",
  • "firstName": "Test",
  • "lastName": "User",
  • "meta": {
    },
  • "accounts": {
    }
}

Update user details

This API allows a logged in user to update his own details in the fabric Identity. fabric Identity stores only the infromation that is necessary for user authentication functionality. The other customer details of the user like shipping and communication preferences are to be stored in the customer service APIs of fabric.

Request
header Parameters
Authorization
required
string

Bearer token of the login in user

Example: Bearer <access token of the user>
Request Body schema: application/json
loginId
string

User Login Id

email
string <email>

User Email Id

firstName
string

User First Name

lastName
string

User Last Name

primaryContact
string

User Primary Contact

Responses
200

User Identity Object

403

User is not allowed to perform the action

500

The request was received but an internal error occurred

put/users/self
Request samples
application/json
{
  • "loginId": "sdsdf232ew-123asdaa-1231231",
  • "email": "test.user@foobar.com",
  • "firstName": "Test",
  • "lastName": "Jr",
  • "primaryContact": "+1 650 333 4444"
}
Response samples
application/json
{
  • "id": "1231012312-312-31231asda",
  • "status": "active",
  • "orgId": "4ed1acc6-7799-4bee-856e-91f18ca77d7a",
  • "loginId": "testuser@gmail.com",
  • "isStaffUserFederated": true,
  • "email": "foo@bar.com",
  • "primaryContact": "+1 234 8992341234",
  • "firstName": "James",
  • "lastName": "Bond",
  • "meta": {
    }
}

Change password

This API allows a logged in user to change his password (post login). This API is not applicable when the user has logged in or registered using a social login.

Request
header Parameters
Authorization
required
string

Bearer token of the login in user

Example: Bearer <access token of the user>
Request Body schema: application/json
oldPassword
string

Old password used by the user

newPassword
string

New password being set by the user

Responses
200

Response when the password gets successfully changed

403

User is not allowed to perform the action

500

The request was received but an internal error occurred

post/auth/self/password
Request samples
application/json
{
  • "oldPassword": "myoldPassword",
  • "newPassword": "mynewPassword"
}
Response samples
application/json
{
  • "code": "PASSWORD_CHANGED",
  • "message": "Password changed successfully."
}

Forgot password

This API allows the users to reset their password when they are unable to login. This API is not applicable when the user has logged in or registered using a social login.

Request
Request Body schema: application/json
loginId
string

Login id of the user whose ID should be reset

Responses
200

Successful response when the user reset link is sent to the registered email address.

500

The request was received but an internal error occurred

post/auth/forgot-password
Request samples
application/json
{
  • "loginId": "johndoe@fabric.inc"
}
Response samples
application/json
{
  • "code": "FORGOT_PASSWORD_INITIATED",
  • "message": "If user was found a reset link will be sent to the provided email"
}