Authorization

Any interaction with the products described in this manual must be authorized.

First, send a request to license@spatium.net to obtain a customer key (merchantKey) from the Spatium team.

After that, the authorization is regulated by a separate cloud service that allows customers to register their user accounts, manage security factors and receive tokens for various actions.

Tokens

A detailed description of the service and tokens can be found in the corresponding section of the cloud services documentation.To familiarize yourself with the products, it is enough to understand the basic principle of working with a permission token (permissionToken) and a refresh token (refreshToken).

The permission token has a short lifetime and allows to perform actions authorized by a certain list of access rights, which are specified when requesting the generation of this token.

The refresh token has a long lifetime and stores all the necessary data to generate a new permission token.

Thus, once you request this pair of tokens with credentials, you can update the permission token without the credentials presented in subsequent requests (within the lifetime of the refresh token).

Cloud

The authorization of the work with cloud services is carried out by sending each request with the header Authorization: Bearer token, where token is an permission token received with the help of authorization service. This token can be obtained in two ways:

• as a service - using the /api/permission/issue-by-key endpoint, необходимо предоставить ключ клиента merchantKey. it is necessary to provide the client's merchantKey. This scheme should be used to send non-user account-specific requests to the api from the client backend. You can also use this scheme to familiarize yourself with cloud products.
• as a user account - using the /api/permission/issue-by-factors endpoint, it is necessary to provide a security token (security Token), previously requested for a specific user account with the required security factors in the corresponding request of the /api/security-factor section or received directly when registering the user account. This scheme should be used to send api requests related to a specific user account.

For the general familiarization with cloud products, it is convenient to use the first option, as it does not require preliminary registration of a user account on the authorization service and obtaining a security token for it. It is enough to receive a permission token from time to time with a merchantKey and use it for requests to cloud services.

curl --location --request POST 'https://cloud.spatium.net/authorization/v1/api/permission/issue-by-key' \
--header 'Content-Type: application/json' \
--data-raw '{
"tokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"permissions": [
"read"
],
"payload": "string",
"merchantKey": merchantKey
}'

curl --location --request GET 'https://cloud.spatium.net/address-info-btc-like/v1/api/eth/?address=0x38e9a6dababD958080D1fB58FB18EFF76F6701bD' \
--header 'Authorization: Bearer PermissionToken'

import { AuthorizationSession } from '@spatium/signer-client';
import { uuid, randomBytes } from '@spatium/sdk';
import axios from 'axios';

const auth = new AuthorizationSession(`https://cloud.spatium.net/authorization/v1`, uuid(randomBytes), ['read', 'secret']);

const { data: { securityToken } } = await axios.post(
  `https://cloud.spatium.net/authorization/v1/api/security-factor/credentials`, 
  { username: 'username', password: 'password' },
  { 
    headers: { 
      'request-id': uuid(randomBytes), 
    }, 
  },
).then(({ data }) => data);

await auth.establish([securityToken]);


const token = await auth.getPermissionToken();

const result = await axios.get(
  `https://cloud.spatium.net/address-info-btc-like/v1/api/btc`, 
  { 
    params: { address: 'bc1qe24ajem88k5jgwl7ntqhyxmtgh59wuypl9ag4c' }, 
    headers: { 
      'request-id': uuid(randomBytes), 
      'authorization': `Bearer ${token}`, 
    }, 
  },
).then((result) => result.data);

SDK

The authorization of work with SDK is performed using the AuthorizationSession module of the Spatium Signer Client package.

Beforehand it is necessary to register a user account on the cloud authorization service from the client's backend with the provision of the required security factors using the corresponding endpoint of the /api/account/credentials section (see Registering a user account). Also, issue a security token for it by presenting the required security factors in the corresponding request of the /api/security-factor section (or apply the security token obtained directly when registering the user account).

After initialization of the AuthorizationSession instance, it is necessary to call the establish method using the security token (to issue permission and update tokens). Then any calls of SDK methods in authorized mode are available, obtaining and updating a permission token during these calls are performed automatically.

import { AuthorizationSession,ServiceStorage, SignerClient } from '@spatium/signer-client';
import {
uuid,
randomBytes,
syncDistributedEcdsaKey,
MemoryStorageDriver,
SpatiumCrypto,
} from '@spatium/sdk';
import axios from 'axios';

const auth = new AuthorizationSession(`https://cloud.spatium.net/authorization/v1`, uuid(randomBytes), ['read', 'secret']);

const cache = new MemoryStorageDriver();
const storage = new ServiceStorage(`https://cloud.spatium.net/storage/v1`, auth);

const crypto = new SpatiumCrypto(cache, storage);
const signer = new SignerClient(`https://cloud.spatium.net/signer/v1`, auth, crypto, 15 * 1000);

const { data: { securityToken } } = await axios.post(
  `https://cloud.spatium.net/authorization/v1/api/security-factor/credentials`, 
  { username: username, password: password },
  { headers: { 
    'request-id': uuid(randomBytes), 
    }, 
  },
).then(({ data }) => data);

await auth.establish([securityToken]);

const secretId = 'uuidv4';
const syncSessionId = 'uuidv4';

try {
  await signer.connect(10 * 1000);

await signer.generateDistributedSecret(secretId);

const publicKey = await syncDistributedEcdsaKey(signer, secretId, syncSessionId, 'secp256k1', 0, 0);
} finally {
  await signer.disconnect();
}

IMPORTANT! When using the AuthorizationSession module in standby mode, permission, and security tokens are not updated periodically. That’s why the session will expire when the lifetime of the refresh token ends. However, you can periodically call the refresh method or call the establish method when the session expires.

User account registration

The user account registration process should be performed from the client’s backend.

First, it is necessary to obtain a permission token with the right to create a user account (merchantKey should have the required permission rights) using the /api/permission/issue-by-key endpoint. To ensure security, a static token identifier corresponding to the client backend service should be used in this request.

import axios from 'axios';

const { data: { permissionToken: { permissionToken } } } = await axios.post(
  `https://cloud.spatium.net/authorization/v1/api/permission/issue-by-key`, 
  { 
    tokenId: '3fa85f64-5717-4562-b3fc-2c963f66afa6', 
    permissions: [
      'register'
    ], 
    merchantKey: 'merchantKey',
  }, 
  { 
    headers: { 
      'request-id': uuid(randomBytes), 
    }, 
  },
).then(({ data }) => data);

Then, with the obtained permission token, it is possible to register a user account with the provision of the necessary security factors using the corresponding endpoint of the api/account section

import axios from 'axios';

const { data: { securityToken } } = await axios.post(
  `https://cloud.spatium.net/authorization/v1/api/account/credentials`, 
  { 
    username: "CoolUser", 
    password: "A.1234567", 
  }, 
  { 
    headers: { 
      'request-id': uuid(randomBytes), 
    }, 
  },
).then(({ data }) => data);

For the convenience of further permission token retrieval for a registered user account, the endpoints of the api/account section immediately return a security token.