Authentication
The @blocklet/server-js library offers two primary methods for authenticating API requests: Auth Tokens and Access Keys. The method you choose depends on your application's environment and security requirements.
- Auth Token (Bearer Token): Ideal for client-side applications (e.g., web browsers) where a user has an active session. It's a simple, temporary credential.
- Access Key: Designed for server-to-server communication or programmatic access. It uses a key pair to sign requests, providing a more secure and long-term authentication solution.
Using an Auth Token#
This is the simplest way to authenticate. After a user logs in to your application, you typically receive a session token. You can configure the client instance to use this token for all subsequent requests.
The client will automatically include the token in an Authorization: Bearer <token> header.
setAuthToken(token)#
Configures the client instance to use the provided bearer token.
Parameter | Type | Description |
|---|---|---|
|
| The authentication token obtained after a user session is established. |
Example
const BlockletServerClient = require('@blocklet/server-js');
// Initialize the client
const client = new BlockletServerClient('http://localhost:4000/api');
// Assume you receive this token after a user logs in
const userAuthToken = 'your-long-auth-token-string';
// Set the token for the client instance
client.setAuthToken(userAuthToken);
// All subsequent API calls will be authenticated
async function fetchNodeInfo() {
try {
const { info } = await client.getNodeInfo();
console.log('Successfully fetched node info:', info.name);
} catch (error) {
console.error('API call failed:', error.message);
}
}
fetchNodeInfo();Using an Access Key#
For backend services or scripts, using an Access Key is more secure and appropriate. This method is available in the Node.js version of the client. It uses a key ID and a secret to generate a unique signature for each request, preventing replay attacks.
setAuthAccessKey({ accessKeyId, accessKeySecret, type })#
Configures the Node.js client to sign requests using an access key and secret.
Parameter | Type | Description |
|---|---|---|
|
| The ID of the access key. For wallet-based types, this is the wallet address. |
|
| The secret key used for signing. For wallet-based types, this is the wallet's private/secret key. |
|
| The signing algorithm or wallet type. Common values include |
Wallet-Based Signatures#
This is the most common and secure method for access keys. The client uses a wallet derived from your secret key to sign a message composed of the current timestamp and the accessKeyId.
Example
// In a Node.js environment
const BlockletServerClient = require('@blocklet/server-js');
const client = new BlockletServerClient('http://localhost:4000/api');
client.setAuthAccessKey({
accessKeyId: 'z1SEXAMPLEa32f143a4115e589a19b88b19', // The wallet address
accessKeySecret: 'zskEXAMPlE4158f96e1b3d6a7e0f2b3844814e5b98a143a4115e589a19b88b19',
type: 'eth', // The wallet type
});
async function fetchProtectedData() {
try {
// This call is now authenticated with a calculated signature
const result = await client.getAccessKeys();
console.log('Access keys:', result.list);
} catch (error) {
console.error('Failed to fetch access keys:', error.message);
}
}
fetchProtectedData();Other Signature Types (sha256, totp)#
The client also supports simpler signing mechanisms like SHA256 hashing and Time-based One-Time Passwords (TOTP) for specific use cases.
SHA256 Example
const BlockletServerClient = require('@blocklet/server-js');
const client = new BlockletServerClient('http://localhost:4000/api');
client.setAuthAccessKey({
accessKeyId: 'my-custom-app-key-id',
accessKeySecret: 'a-very-long-and-secure-secret-string',
type: 'sha256',
});TOTP Example
const BlockletServerClient = require('@blocklet/server-js');
const client = new BlockletServerClient('http://localhost:4000/api');
client.setAuthAccessKey({
accessKeyId: 'my-totp-service-id',
accessKeySecret: 'JBSWY3DPEHPK3PXP', // A Base32 encoded secret for TOTP
type: 'totp',
});How Access Key Authentication Works#
Here is a diagram illustrating the request signing and validation process when using an access key.
With a clear understanding of both authentication methods, you can now securely interact with Blocklet Server. To explore the available API operations, please proceed to the API Reference.