Authentication

This section explains how to authenticate into W3Block services ecosystem

All of W3block API services shares the same authentication that can be obtained using ID services. Basically, ID controls all of users, companies and permissions and besides that, it can generate JWT tokens that can be used to authenticate requests into our entire ecosystem. Above you can see our authentication flow.

W3block authentication flow

How to Authenticate

To authenticate, you must use the ID services API endpoint above:

post

Body

application/json

emailstringRequiredExample: [e-mail]

passwordstringRequiredExample: P@ssw0rd

tenantIdstringOptionalExample: 00000000-0000-0000-0000-000000000001

Responses

201Success

application/json

401Error

application/json

429Error

application/json

post

/auth/signin

HTTPcURLJavaScriptPython

POST /auth/signin HTTP/1.1
Host: api-id.w3block.io
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "email": "[e-mail]",
  "password": "P@ssw0rd",
  "tenantId": "00000000-0000-0000-0000-000000000001"
}

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjOTFhZDIyOC05NTdhLTQxMDQtOWIxMy0xOGUyNzk5MDE4MDMiLCJpc3MiOiI1YmQ5NmFhZi0xODg4LTQ5M2UtYjg0ZS03YzU0YTQ3MzE4NjgiLCJhdWQiOiI1YmQ5NmFhZi0xODg4LTQ5M2UtYjg0ZS03YzU0YTQ3MzE4NjgiLCJlbWFpbCI6InBpeHdheUB3M2Jsb2NrLmlvIiwibmFtZSI6IlBpeHdheSIsInJvbGUiOiJhZG1pbiIsImNvbXBhbnlJZCI6IjViZDk2YWFmLTE4ODgtNDkzZS1iODRlLTdjNTRhNDczMTg2OCIsInRlbmFudElkIjoiNWJkOTZhYWYtMTg4OC00OTNlLWI4NGUtN2M1NGE0NzMxODY4IiwidmVyaWZpZWQiOnRydWUsImlhdCI6MTY1ODUwODE3OSwiZXhwIjoxNjkwMDQ0MTc5fQ.L_0Py_M_1Ija_QnFKl7uNZr9fpkcVpZSv-tnNf07YQOcIEuR-TU0S9DMkLkHtmYrHKJe_vzzf14FS7J43NYVILn3NrXb-pC5-YO8V3JnMX4yBsgM2t0xdqEW6fqILk8_oxXsDFAhNkaNeBa2ljNilDncSepps7q69PP-TP7JVkjKQg2Za_E6ZwU",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6InJlZnJlc2gifQ.eyJzdWIiOiJjOTFhZDIyOC05NTdhLTQxMDQtOWIxMy0xOGUyNzk5MDE4MDMiLCJpc3MiOiI1YmQ5NmFhZi0xODg4LTQ5M2UtYjg0ZS03YzU0YTQ3MzE4NjgiLCJhdWQiOiI1YmQ5NmFhZi0xODg4LTQ5M2UtYjg0ZS03YzU0YTQ3MzE4NjgiLCJ0ZW5hbnRJZCI6IjViZDk2YWFmLTE4ODgtNDkzZS1iODRlLTdjNTRhNDczMTg2OCIsInRva2VuSGFzaCI6ImJiMmFjMzE4M2EzZDZlMDljYTI2ZDkzNDEzNjQyNzU4MGY3Yjc5NWVlYWU3YTFlYzUzNDU2MjU5NThjMDZhYWQiLCJpYXQiOjE2NTg1MDgxNzksImV4cCI6MTY5MDA0NDE3OX0.au6dcpbcSmF134J335G4CymEUlwK39TT-4jXQwEUm0zRokFBiHpkXZzy23fTufyo_XzW_Tr_IUfO9b_y5e0thjIfvng4dS7akdeQAykcN7nRhwNBtqCVZxFHyZE39yzz38JLMwC00EtaKowM6lPykJYC5qZC0bBj4g4Yb1GG9IU5dQodibdXj00",
  "data": {
    "sub": "00000000-0000-0000-0000-000000000001",
    "iss": "00000000-0000-0000-0000-000000000001",
    "aud": "00000000-0000-0000-0000-000000000001",
    "exp": 1516239022,
    "iat": 1516239022,
    "tenantId": "00000000-0000-0000-0000-000000000001",
    "email": "[e-mail]",
    "name": "Jon Doe",
    "roles": "user",
    "verified": true,
    "type": "user",
    "emailVerified": true,
    "phoneVerified": true
  },
  "isNewUser": false,
  "isPrivateEmail": false,
  "profile": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[e-mail]",
    "phone": "[phone]",
    "verified": true,
    "phoneVerified": true,
    "emailVerified": true,
    "roles": [
      "user"
    ],
    "i18nLocale": "pt-br",
    "name": "John Doe",
    "tenantId": "123e4567-e89b-12d3-a456-426614174000",
    "mainWalletId": "123e4567-e89b-12d3-a456-426614174000",
    "addressId": "123e4567-e89b-12d3-a456-426614174000",
    "address": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "street": "Street",
      "number": "123",
      "district": null,
      "complement": null,
      "city": "Sao Paulo",
      "state": "Sao Paulo",
      "country": "Brazil",
      "postalCode": null,
      "coordinates": null
    },
    "mainWallet": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "tenantId": "123e4567-e89b-12d3-a456-426614174000",
      "address": "0x0000000000000000000000000000000000000000",
      "ownerId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "vault",
      "status": "ready",
      "owner": {}
    },
    "wallets": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "tenantId": "123e4567-e89b-12d3-a456-426614174000",
        "address": "0x0000000000000000000000000000000000000000",
        "ownerId": "123e4567-e89b-12d3-a456-426614174000",
        "type": "vault",
        "status": "ready",
        "owner": {}
      }
    ],
    "contexts": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "createdAt": "2025-12-15T18:04:30.421Z",
        "updatedAt": "2025-12-15T18:04:30.421Z",
        "tenantId": "123e4567-e89b-12d3-a456-426614174000",
        "contextId": "text",
        "userId": "text",
        "status": "created",
        "context": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "createdAt": "2025-12-15T18:04:30.421Z",
          "updatedAt": "2025-12-15T18:04:30.421Z",
          "description": "text",
          "slug": "text",
          "tenantId": "123e4567-e89b-12d3-a456-426614174000",
          "type": "user_properties",
          "maxSubmissions": 1,
          "isPreOrder": 1
        },
        "logs": [
          {
            "inputIds": [
              "text"
            ],
            "moderatorId": "123e4567-e89b-12d3-a456-426614174000",
            "reason": "text",
            "registerAt": "2025-12-15T18:04:30.421Z",
            "status": "approved"
          }
        ],
        "approverUserId": null
      }
    ],
    "createdAt": "2025-12-15T18:04:30.421Z",
    "updatedAt": "2025-12-15T18:04:30.421Z",
    "kycStatus": "noRequired",
    "avatarUrl": "text",
    "referrerUser": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "[e-mail]"
    }
  }
}

You can also use our node-js ID SDK to authenticate.

Authenticating as user

If you want to authenticate some user registered in your tenant base, you can use the following sdk code:

import { W3blockIdSDK } from '@w3block/sdk-id';
const idSdk = new W3blockIdSDK({
    baseURL: 'https://api-id.pixway.io',
    autoRefresh: true,
});
await idSdk.authenticate({
    email: '[e-mail]',
    password: '<change.me>',
    tenantId: '<your tenant id (also known as your company id)>',
});
const jwtToken = idSdk.getAuthToken();
console.log(`My authentication token id: ${jwtToken}`);

Authenticating as tenant

Sometimes you want to integrate some application into our service. This way, is not common to authenticate as a common user, so you want to authenticate as a tenant or basically using a tenant api key and secret. Above you can see some example on how to authenticate using this method.

import { W3blockIdSDK } from '@w3block/sdk-id';
const idSdk = new W3blockIdSDK({
    baseURL: 'https://api-id.pixway.io',
    autoRefresh: true,
});
await idSdk.authenticate({
    key: '<your tenant key>',
    secret: '<your tenant secret>',
    tenantId: '<your tenant id (also known as your company id)>',
});
const jwtToken = idSdk.getAuthToken();
console.log(`My authentication token id: ${jwtToken}`);

Using the authentication token in our api services

To be authenticated into our api services, you must pass the obtained jwt token into the Authorization request header using the pattern of bearer tokens

Example:

Authorization: Bearer <JWT token>

You can also directly authenticate into our services using the tenant credentials without getting the tenant jwt token. To do that, you just need to inform in the request headers the following params:

• x-w3block-id: Your tenant id

• x-w3block-api-key: Your tenant api key

• x-w3block-secret: Your tenant api secret

This way, the api service that you're calling will automatically handle the tenant authentication without the need of manually get the JWT token as example above.