Skip to Content
DocumentationToolingUtilitiesSession Key Generator

Session Key Generator

Session Key Generator helps you generate session keys for signing purposes when deploying and querying Views through the Watch SDK.

NOTE

You can use the keygen, @polkadot/extension-dapp/ or @polkadot/Keyring packages to generate new session keys. For detailed instructions, refer to the "Quickstart" guide

Prerequisites

This guide assumes you've already set up the following requisites:

  1. Need an account in any substrate-based wallets like Polkadot.JS , SubWallet , Enkrypt , and Talisman . Refer to Wallet Support  for more details
  2. Need the latest version of npm  or yarn 

Installation

Install the Watch Client (timegraph-js) and the WASM Package (timegraph-wasm) using your preferred package manager

npm i @analog-labs/timegraph-js
npm i @analog-labs/timegraph-wasm

The Watch Client offers client-side features for Analog Watch interaction, while the WASM Package contains efficient WebAssembly compiled code that runs directly in the browser or Node.js environment.

Authentication

The WASM Package supports both the web and node environments. The authentication process involves five steps:

1. Create a certificate

Create a certificate using your Substrate-supported wallet address as follows:

import init, { new_cert } from '@analog-labs/timegraph-wasm';
 
// initialize the Web Assembly in the JS Environment.
init();
 
// <Wallet Address> must be polkadot/substrate supported.
// <Role> can be "user" or "developer"
const [certificate, secret] = new_cert('<Wallet Address>', '<Role>');

Notice that init() can only be used in a web environment.

Response

[
    [0,0,0,1,0,0,0,32,0,0,0.......]
    "9yPmWeRLcpGn9rAeqg8npRyBmgA9D8D94KPTpfkD8Kgd"
]

2. Setup the wallet

Install the necessary packages to sign the wallet

npm i @polkadot/extension-dapp @polkadot/util @polkadot/util-crypto

Paste the below code in your IDE,

const { Keyring } = require('@polkadot/keyring');
const { addFromJson } = require('@polkadot/util');
 
const keyring = new Keyring({ type: 'sr25519' });
const keypair = keyring.addFromJson(/* JSON object obtained from exporting the wallet goes here */);
keypair.unlock("<PASSWORD>");

3. Generate the API key

To proceed, follow these steps

  1. Get keypair from above "setup the wallet" step
  2. Get secret & certificate from first step "create a certificate" step
import { build_apikey } from '@analog-labs/timegraph-wasm';
import { injector } from '@polkadot/extension-dapp'
import { hexToU8a } from '@polkadot/util';
 
const signedData = await injector.signer.signRaw({
    address: "<wallet address>",
    data: certificate, // get from "create a certificate" step
    type: "bytes",
});
 
const apiKey = build_apikey(secret,certificate, hexToU8a(signedData.signature));

Response

"apiKey":{
   "key":"HtACKxQe9dx4Xmg8d1sSd7PQnzvNKSS9ViBb2Aq8Fdo",
   "secret":"9yPmWeRLcpGn9rAeqg8npRyBmgA9D8D94KPTpfkD8Kgd",
   "cert":"111CfKkxwN6abhKrnZ4wKEWdpagvfNqe6iUR5Gg....."
}

4. Generate the session key (SSK)

Follow these steps to generate the session key (SSK):

  1. Encode SSK with wallet address and UserId.
  2. Sign the encoded SSK using the Substrate wallet signer.
  3. Build the SSK.

The code below illustrates these processes:

import init, { encode_ssk, build_ssk  } from '@analog-labs/timegraph-wasm'
import {injector } from '@polkadot/extension-dapp'
import { hexToU8a} from '@polkadot/util';
import { encode_ssk, build_ssk } from '@analog-labs/timegraph-wasm';
 
const sskData = encode_ssk({
      ns: 0,
      key: '<Wallet Address>',
      user_id: 1,
      expiration: 0,
});
 
const sskSignature = await injector.signer.signRaw({
      address: '<Wallet Address>',
      data: ssk_data,
      type: 'bytes',
});
 
const ssk = build_ssk(sskData, hexToU8a(sskSignature.signature));

Response

{
   "ssk":"0;EFVS6JNJ7ah615F69cTHsDrUP2vziy1943hyW6LUbkfr;0;*;1;26528g8cdQfzBw2ue85Hbkcw3cpRmrfrhjhpEScxeKhQuVMYCKzoucNcXUmXEiypg9G7188n9h2pzLCRwD1BFFk3"
}

5. Create an account

With the SSK data generated, you can now create an account by providing the wallet address and SSK to the SDK:

import { TimegraphClient } from '@analog-labs/timegraph-js';
 
const timegraphClient = new TimegraphClient({
    url: '<URL>',
    sessionKey: '<SSK>',
});
 
// paste below code snippet into the async function
const createUser = await timegraphClient.user.create({ address: '<wallet address>' });

Response

"response":{
   {
      "userId":111,
      "wallet":"5GWqFcdT8ugZW8fZhZHQzcx96M2jQYLV7M9KMozYPzLfEdR9",
      "userRole":"developer",
      "subgraph":111
   }
}

6. Validate the API key certificate

To validate the certificate data for a new API key and save it in storage, you must pass a valid SSK (Session Signing Key) for the signing account as follows:

  1. Ensure you have an existing account in the Watch Portal.
  2. The SSK can be downloaded by clicking on the download icon next to the wallet address in the "Profile" section of the Watch Portal.

The code below illustrates these processes:

import { TimegraphClient } from '@analog-labs/timegraph-js';
 
const timegraphClient = new TimegraphClient({
    url: '<URL>', // timegraph GraphQL endpoint (ex: timrgraph.testnet.analog.one/graphql)
    sessionKey: '<SSK>', // valid <SSK> 
});
 
// paste below code snippet into the async function
const certifyKey = await timegraphClient.apiKey.certify({ cert: '<certificate>' }); // Take <certificate> from above generated apiKey

Response

"response":{
   "certifyKey":{
      "userId":100:"111CfKkxwN6abhKrnZ4wKEWdpagvfNqe6iUR5Gg.....",
      "key":"HtACKxQe9dx4Xmg8d1sSd7PQnzvNKSS9ViBb2Aq8Fdo",
      "role":"developer",
      "status":"active"
   }
}

Entire Session Key Generation in one go

The code below illustrates the whole ssk generation process:

You have to change two things manually in below code snippet

  1. Connect wallet
  2. Existed user session key 
import { Keyring } from "@polkadot/keyring";
import { TimegraphClient } from "@analog-labs/timegraph-js";
import {cryptoWaitReady} from "@polkadot/util-crypto";
import { new_cert, encode_ssk, build_ssk, build_apikey } from '@analog-labs/timegraph-wasm';
 
const timegraphGraphqlUrl = "https://timegraph.testnet.analog.one/graphql";
 
async function sessionKeyGeneration(){
  await cryptoWaitReady();
  const keyring = new Keyring({ type: "sr25519" });
 
  const keypair = keyring.addFromJson(/* JSON object obtained from exporting the wallet goes here */);
  keypair.unlock("<PASSWORD>");
 
  // build api key
  const [certificate, secret] = new_cert(keypair.address, "developer"); 
  const signedData = keypair.sign(certificate);
  const apiKey = build_apikey(secret,certificate, signedData);
  
  // if user is not existed for above wallet then create new using existed timegraph user otherwise comment out below two steps
  const validTimegraphUser = new TimegraphClient({
    url: timegraphGraphqlUrl,
    sessionKey: "<Existed_User_Valid_SSK>",
  });
 
  // create a new user
  await validTimegraphUser.user.create({ address: keypair.address })
 
  const sskData = encode_ssk({
    ns: 0,
    key: keypair.address,
    user_id: 1,
    expiration: 0 // expiration time in milliseconds
  });
 
  const signedSSKData = keypair.sign(sskData);
  const ssk = build_ssk(sskData, signedSSKData);
  
  const newTimegraphUser = new TimegraphClient({
    url: timegraphGraphqlUrl,
    sessionKey: ssk,
  });
 
  // store api key in timegraph's new user account
  await newTimegraphUser.apiKey.certify({ cert: apiKey.cert });
 
  // print ssk
  console.log(ssk)
 
  // check the ssk
  console.log(await newTimegraphUser.apiKey.list())
  
}
 
sessionKeyGeneration();

Response

"response":{
   "0;AiUTRFFP7n7AVuj6GBKHTD6HYcr84XY7xXYH1V2v1AqY;6000;*;1;5AEqK6TDyKASrApEJy9cyG3MPiN1uNck1TdRmgN825hQwwnRy8mgdN2Fut6VGRCtBS7YNFusc99ePXkoLd3c6uoG"
[
  {
    userId: 000001,
    key: 'abcd9ocJnDJP72HVuQPLbyEU9MLw8REw53cyxHWHK1yz',
    cert: [
      0, 0, 0,   1, 0, 0, 0,  32, 0, 0, 0, 144,
      0, 0, 0,  89, 0, 0, 0,  10, 0, 0, 0,  30,
      0, 0, 0,  48, 0, 0, 0,  19, 0, 0, 0, 130,
      0, 0, 0,   0, 0, 0, 0, 233, 0, 0, 0, 224,
      0, 0, 0,  16, 0, 0, 0, 101, 0, 0, 0, 208,
      0, 0, 0,  74, 0, 0, 0,  43, 0, 0, 0, 233,
      0, 0, 0, 121, 0, 0, 0, 142, 0, 0, 0,  70,
      0, 0, 0, 183, 0, 0, 0,  68, 0, 0, 0, 163,
      0, 0, 0, 223,
      ... 428 more items
    ],
    role: 'developer',
    status: 'enabled'
  }
]
}

Enable the previously revoked API key

You can also enable the previously revoked API key by passing a valid session key for the key's owner like this:

import { TimegraphClient } from '@analog-labs/timegraph-js';
import { cryptoWaitReady } from '@polkadot/util-crypto';
 
const timegraphClient = new TimegraphClient({
    url: '<URL>',
    sessionKey: '<SSK>',
});
 
// paste below code snippet into the async function
const enableAPIKey = timegraphClient.apiKey.enable({ key: '<Api key>' });

Response

"response":{
   "certifyKey":{
      "userId":100"cert":"111CfKkxwN6abhKrnZ4wKEWdpagvfNqe6iUR5Gg.....",
      "key":"HtACKxQe9dx4Xmg8d1sSd7PQnzvNKSS9ViBb2Aq8Fdo",
      "role":"developer",
      "status":"active"
   }
}

Revoke an API Key

Likewise, you can also revoke an API key by passing a valid SSK for the key's owner in the Authorization header:

import { TimegraphClient } from '@analog-labs/timegraph-js';
 
const timegraphClient = new TimegraphClient({
    url: '<URL>',
    sessionKey: '<SSK>',
});
 
// paste below code snippet into the async function
const revokeAPIKey = await timegraphClient.apiKey.revoke({ key: '<Api key>' });

Response

"response":{
   "certifyKey":{
      "userId":100"cert":"111CfKkxwN6abhKrnZ4wKEWdpagvfNqe6iUR5Gg.....",
      "key":"HtACKxQe9dx4Xmg8d1sSd7PQnzvNKSS9ViBb2Aq8Fdo",
      "role":"developer",
      "status":"active"
   }
}
UtilitiesDmail