☑️Quick Start

This guide will walk you through the steps to register, log in, and fetch a user profile using the API. It also explains how to use the Auth-Key header for authorized requests and Brand-URL header for all requests.

Prerequisites

• Ensure you have access to the API base URL (e.g., https://api.example.com) that mean you has already brand.

• Tools like curl, Postman, or any HTTP client to make API requests.

Step 1: Register a New User

To use the API, you first need to register a new user. Send a POST request to the registration endpoint with the required user details. Visit Register a new user

Request

curl -L \
  --request POST \
  --url 'https://protocol.jframework.io/api/v1/users/register' \
  --header 'Brand-URL: example.com' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "john.doe",
    "phoneNumber": "[phone]",
    "password": "password",
    "emailAddress": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe",
    "nickName": "JohnDoe",
    "referralCode": "INVITATIONCODE",
    "timeZoneId": "KIplKnap0Kp"
  }'

Response

On successful registration, you will receive a response with the user details:

{
  "success": true,
  "statusCode": 201,
  "message": "The request was successful.",
  "data": "2rlzM7wMrxdOkPsa",
  "errors": []
}

Step 2: Sign In to Get Auth-Key

After registration, sign in to obtain the Auth-Key, which is required for authorized API requests. Visit Authentication

Request

bashCopy

curl -L \
  --request POST \
  --url 'https://protocol.jframework.io/api/v1/users/auth' \
  --header 'Brand-URL: example.com' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "john.doe",
    "password": "password"
  }'

Response

On successful authentication, you will receive an Auth-Key in the response:

{
  "success": true,
  "statusCode": 200,
  "message": "The request was successful.",
  "data": {
    "id": "asdasdcwAqrNxIT0xQdkMvR",
    "username": "user",
    "emailAddress": "[e-mail]",
    "Auth-Key": "abc123xyz456="
  },
  "errors": []
}

Save the Auth-Key value for use in subsequent requests.

Step 3: Fetch User Profile (Authorized Request)

To fetch the user profile, you need to include the Auth-Key in the request header. This API requires authorization.

Request

GET /api/v1/user/me
Auth-Key: abc123xyz456
Brand-URL: example.com

• Auth-Key: The key obtained from the login response.

• Brand-URL: A required header for authorized requests (replace example.com with your brand's URL).

Response

The response will include the user's profile details:

{
  "success": true,
  "statusCode": 200,
  "message": "The request was successful.",
  "data": {
    "brandId": "xZrwkBM58VN",
    "parentUser": {
      "code": "PZBAAE",
      "avatar": "https://www.jframework.io/admin.jpg",
      "packageId": "yDpX0wAbpGRqjv3l",
      "packageCode": "STANDARD",
      "emailAddress": "[e-mail]",
      "nickName": "Admin",
      "roles": [
        "Admin"
      ],
      "id": "2rlzM7wMPlamsSa"
    },
    "code": "AABA24461C0E194BEF3E",
    "username": "john.doe",
    "firstName": "John",
    "lastName": "Doe",
    "nickName": null,
    "avatar": "https://www.johndoe.com/avatar.jpg",
    "emailAddress": "[e-mail]",
    "phoneNumber": "+01234567890",
    "website": "https://www.johndoe.com",
    "bio": null,
    "type": "EndUser",
    "isEmailAddressVerified": null,
    "isUserVerified": null,
    "riskMark": 50,
    "roles": [
      {
        "parentBrandId": "xZrwkBM58VN",
        "guid": "3fac654f-d9d1-45e7-907a-cb3c63435cc7",
        "code": "ADMIN",
        "name": "Admin",
        "description": "Admin",
        "tags": "Admin",
        "isSystem": true,
        "permissions": [
          "USER.CREATE"
        ],
        "id": "2rlzM7w"
      }
    ],
    "referralCode": "AABAAE",
    "testMode": false,
    "tags": null,
    "status": "Active",
    "isSystem": false,
    "package": "STANDARD",
    "packageId": "yDpX0wAbpGRqjv3l",
    "languageCode": "vi-VN",
    "timeZoneId": "QlzwLjGaKvAvbD5x",
    "expiryDate": "2025-04-06T08:57:14.243647Z",
    "themeStyle": "light",
    "enableSignInDetection": true,
    "isUserIntegration": false,
    "id": "2rlzM7wMrxdPLmsza",
    "createdDate": "2025-03-07T08:57:14.243647Z"
  },
  "errors": []
}

---

Step 4: Using Auth-Key for Other Authorized APIs

For any API that requires authorization, you must include the Auth-Key headers in your request. For example:

Example: Fetch User notifications

GET /api/v1/notifications
Auth-Key: abc123xyz456
Brand-URL: example.com

Example: Update User Profile

curl -L \
  --url 'https://protocol.jframework.io/api/v1/notifications' \
  --header 'Brand-URL: example.com' \
  --header 'Auth-Key: abc123xyz456'

---

Step-by-Step Workflow

1. Register a new user using the /api/v1/user/register endpoint.

2. Log in using the /api/v1/users/auth endpoint to obtain the Auth-Key.

3. Fetch the user profile using the /api/v1/user/me endpoint with the Auth-Key and Brand-URL headers.

4. Use the Auth-Key for other authorized APIs as needed.

---

Best Practices

• Always include the Brand-URL header in every request to identify the brand.

• Store the Auth-Key securely and do not expose it in client-side code.

• Handle API errors gracefully (e.g., invalid Auth-Key, expired session).

\