Authentication 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.

Authorize with and without PKCE

Use this API to authenticate user app(s) with fabric Identity. This API is not needed for system apps 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 user app 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.

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"
}