Authentication

The JFW API uses Auth Keys to authenticate Protocol requests. You can obtain an Auth Key by either using the JFW libraries or calling the following API endpoint:

Authenticates the user with the given email and password.

post

After a successful authentication, the following headers must be included to register or update the user’s device:

• X-Device-Code: A unique identifier for the device.
• X-Device-Token: The Firebase device token used for push notifications.
• X-Device-Name: The name/model of the device.
• X-App-Version-Number: The version of the application.
• X-Os-Device: The operating system of the device (iOS, Android).

Header parameters

Brand-URLstringRequired

The brand URL of the request. This is used to identify the brand.

Example: YOUR_BRAND_URL

Body

application/jsontext/jsonapplication/*+json

This is the model class for UserAuthentication.

usernamestring · min: 1Required

This represents the username of the user.

Example: john.doe

emailAddressstring · nullableRead-onlyOptional

The email address of the user to authenticate.

passwordstring · min: 1Required

This represents the password of the user.

Example: password

Responses

200

The request was successful.

application/json

The API result model with data.

successbooleanRead-onlyRequired

This is the flag to indicate whether the API call is successful or not.

statusCodeinteger · int32Read-onlyRequired

This is the HTTP status code. This is used to determine the status code to be returned to the client.

messagestring · min: 1Required

This is the message to be displayed to the user.

401

The username or password incorrect.

application/json

429

API call exceeded rate limit due to too many requests.

application/json

post

/api/v1/users/auth

HTTPcURLJavaScriptPython

POST /api/v1/users/auth HTTP/1.1
Host: protocol.jframework.io
Brand-URL: text
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "username": "john.doe",
  "emailAddress": "john.doe",
  "password": "password"
}

application/jsontext/jsonapplication/*+json

{
  "success": true,
  "statusCode": 200,
  "message": "The request was successful.",
  "data": {
    "id": "asdasdcwAqrNxIT0xQdkMvR",
    "username": "user",
    "emailAddress": "[e-mail]",
    "phoneNumber": "[phone]",
    "authKey": "8mgBXMwMchIWWlLmvEL9RasdasdcwAqrNxIT0xQdkMvRndmSjh4YmtOcjdZb2taUT09N1J5bVdzRDlUUWhhRFFwdlRhemk4ZDFuaFdHajYzVXlYLy9valkwYXpuQT0=",
    "refreshAuthKey": "Li48YUZxXkS52eNwx5D2yA4axptAvd1IWGxCZndDODFQTTZ5VnNoOVFLb1RGdz09cmlLTXQ4c1Y0RENDSHQ1QWtMU2I4a0tOem05QmtNd0pTUlpGenpsc0hBOD0=",
    "expiresIn": "2026-02-25T01:03:23.913165Z"
  },
  "errors": []
}

After having the Auth Key, you have to put that Auth Key and Brand URL to your HTTP request header to use other API endpoints.

Brand-URL: your-domain.com
Auth-Key: your-key-is-here

Instead of an API key, we use a combination of Brand-URL and Auth-Key to gain access to API endpoints. To access those API endpoints that need certain permissions, we must include Auth-Key, brandUrl, or both in the request body. These values may not match the ones in the request headers.

If you need to use the device access, add the key header Device-Code before using the device access feature.