Client Initialization & Auth

The SpaceClient is the primary interface for interacting with the DID Space network. Before you can upload files or manage data, you must first create an instance of the client with the correct configuration and authentication credentials. This guide will walk you through the various strategies for initializing and authenticating the SpaceClient.

All configuration is passed to the client through a single SpaceClientOptions object in its constructor.

import { SpaceClient } from '@blocklet/did-space-js';

const spaceClient = new SpaceClient({
  // ... your options go here
});

The most critical part of this configuration is the auth object, which determines how your requests will be authenticated.

Authentication Strategies#

The SDK offers three primary methods for authentication, designed to fit different use cases. You should choose the one that best suits your application's environment and security requirements.

1. Using Endpoint & Wallet (Recommended)#

This is the most common and secure method, especially when developing within a Blocklet environment where a user's wallet is readily available. It uses the user's wallet to sign requests, providing a robust, decentralized authentication mechanism.

This method corresponds to the SpaceClientOptionsEndpointAuth interface.

Configuration

Example

import { SpaceClient } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

// In a Blocklet environment, the wallet is easily accessible.
const wallet = getWallet();

// The endpoint is specific to a user's space and the app's DID.
const endpoint =
  'https://cedcaa27-znkomkclejcfbjaxw9knzzebmzmqrxjnn9bb.did.abtnet.io/api/space/z3T6EHN7sLhH5cty1PshDeSipeG7JNxEVaRFS/app/zNKabhhwdvVmXjtRTtSHk2YQz4pdDPStV289/';

const spaceClient = new SpaceClient({
  auth: {
    wallet: wallet,
    endpoint: endpoint,
  },
});

// The client is now ready to send signed requests.

2. Using an Authorization Token#

This method is suitable for scenarios where you have a short-lived bearer token. This is common in traditional web applications or for server-to-server communication where a wallet might not be present.

This method corresponds to the SpaceClientOptionsAuthorizationAuth interface.

Configuration

Example

import { SpaceClient } from '@blocklet/did-space-js';

const authToken = 'your-secure-authorization-token';

const spaceClient = new SpaceClient({
  url: 'https://www.didspaces.com/app',
  auth: {
    authorization: authToken,
  },
});

// The client will now use the token for authentication.

3. Using an Access Key#

This method is designed for backend services or automated scripts that need long-term access to a DID Space. It uses a secret key for authentication, similar to how many cloud services grant API access.

This method corresponds to the SpaceClientOptionsAccessKeyAuth interface.

Configuration

Example

import { SpaceClient } from '@blocklet/did-space-js';

const secretKey = 'your-long-term-secret-key';

const spaceClient = new SpaceClient({
  url: 'https://www.didspaces.com/app',
  auth: {
    secretKey: secretKey,
  },
});

// The client is configured for server-side or automated access.

Other Important Options#

Besides authentication, the SpaceClientOptions object accepts a few other useful parameters.

Now that you understand how to initialize and authenticate the SpaceClient, the next logical step is to learn how the SDK secures your requests under the hood. To dive deeper into the security model, please proceed to the Request Signing documentation.