Comment on page
🛠
Configuring SSX
SSX Configuration Guide
SSX enables an easy way for users to sign in on behalf of a Gnosis Safe multisig on your platform that they have been delegated access to. It provides an easy flow that users can take to either log in as themselves or on behalf of the multisig. Defaults to
false.enableDaoLogin: boolean;
Here is an example of how you enable it:
const ssx = new SSX({
enableDaoLogin: true
});
SSX has modules to aggregate more features into the library. By default, all modules are disabled (
false) except for the UserAuthorization module, which is mandatory.modules: {
settings?: boolean | SSXStorageModuleConfig;
};
SSXStorageModuleConfig: {
prefix?: string;
hosts?: Array<string>;
autoCreateNewOrbit?: boolean;
};
Here is an example of how you enable it:
Storage Module
const ssx = new SSX({
modules: {
storage: {
prefix: 'app-prefix',
hosts: ['https://kepler.spruceid.xyz'],
autoCreateNewOrbit: true,
}
}
});
For more information about the modules and the methods they enable, you can take a look at the modules' pages:
SSX acts as a super-provider for your app to make multiple resources available to your app with minimal configuration: a web3 provider (to connect to your wallet), an RPC provider (to connect to blockchains), and a server provider (to connect to a server powered by SSX).
providers: {
web3?: SSXProviderWeb3;
server?: SSXProviderServer;
rpc?: SSXRPCProvider;
}
Apps interact with the Ethereum network by accessing the Ethereum JavaScript provider API, which is usually injected into the browser by an Ethereum wallet. SSX works with any wallet by connecting to the wallet's implementation of BrowserProvider, which is passed to the config as seen below.
SSX then manages this wallet connection, creates and displays the Sign-in with Ethereum message, and handles signed messages.
providers: {
web3?: {
driver: BrowserProvider;
}
};
Here is an example of how you enable it:
const ssx = new SSX({
providers: {
web3: {
driver: window.ethereum
}
}
});
The server field is an optional reference to a corresponding server running
ssx-server. Providing the host field enables automatic communication with the server to establish sessions upon successful SIWE signing. ssx and ssx-server have default paths configured for the endpoints (nonce: '/ssx-nonce', login: '/ssx-login' and logout: '/ssx-logout'), but you can override it by providing the property routes. It isn't necessary to override all of them.provider: {
server?: {
host: string;
routes?: {
nonce?: SSXServerRouteEndpointType;
login?: SSXServerRouteEndpointType;
logout?: SSXServerRouteEndpointType;
};
}
};
SSXServerRouteEndpointType: Partial<SSXRouteConfig> | AxiosRequestConfig | string;
SSXRouteConfig: {
url?: string;
method?: 'get' | 'post' | 'put' | 'delete';
/**
* Custom Operation.
* Replace the SSX function called with a function of your own
**/
customAPIOperation?(
params: SSXClientSession | Record<string, any> | any
): Promise<any>;
}
Here is an example of how you use it:
Custom Paths
Custom Methods
Custom Operation
const ssx = new SSX({
providers: {
server: {
host: 'http://localhost:3001'
routes: {
nonce: '/ssx-custom-nonce',
login: '/ssx-custom-login',
logout: '/ssx-custom-logout',
}
}
}
});
const ssx = new SSX({
providers: {
server: {
host: 'http://localhost:3001'
routes: {
nonce: {
url: '/ssx-custom-nonce',
method: 'post'
}
}
}
}
});
const ssx = new SSX({
providers: {
server: {
host: 'http://localhost:3001'
routes: {
nonce: {
url: '/my-custom-nonce',
method: 'post',
customAPIOperation: () => {
return "custom-nonce"
}
}
}
}
}
});
For issues talking to custom endpoints, the options available in the Axios Request Config are valid configuration options and can be used to modify the requests that SSX sends.
SSX supports all JSON RPC providers that are currently supported by
ethers, requiring only the credentials from the desired provider to instantiate it. The SSX library provides valid enumerated options for various RPC providers, but developers can also just use the valid strings.providers: {
rpc?: {
service: string;
network: string;
apiKey: string;
}
};
Here is an example of how you enable it:
predefined
custom
import {
SSXRPCProviders,
SSXInfuraProviderNetworks
} from '@spruceid/ssx-core';
const ssx = new SSX({
providers: {
rpc: {
service: SSXRPCProviders.SSXInfuraProvider,
network: SSXInfuraProviderNetworks.MAINNET,
apiKey: process.env.INFURA_API_KEY ?? '',
},
},
});
const ssx = new SSX({
providers: {
rpc: {
service: 'infura',
network: 'homestead',
apiKey: process.env.INFURA_API_KEY ?? '',
},
},
});
This field enables ENS resolution when signing in. After the sign-in, the ENS data will be available with all other session data.
resolveEns can be a boolean (defaults to false) or an object. resolveEns: boolean | SSXEnsConfig;
SSXEnsConfig: {
/** Enable the ENS resolution on server instead of on client. */
resolveOnServer?: boolean;
/** ENS resolution options. True means resolve all. */
resolve: {
/** Enable ENS name/domain resolution. */
domain?: boolean;
/** Enable ENS avatar resolution. */
avatar?: boolean;
};
}
Here is an example of how you enable it:
boolean
object
const ssx = new SSX({
resolveEns: true
});
const sessionWithENSData = ssx.signIn();
const ssx = new SSX({
resolveEns: {
resolveOnServer: false, // defaults to false
resolve: {
domain: true,
avatar: false
}
}
});
const sessionWithENSData = ssx.signIn();
This feature is available for Polygon Mainnet and Mumbai Testnet. Visit the Lens docs for more information.
This field enables Lens profile resolution when signing in. After a user signs in, the Lens data will be available with all other session data.
resolveLens can be a boolean (default to false) or 'onServer'. resolveLens: boolean | 'onServer';
Here is an example of how you enable it:
boolean
onServer
const ssx = new SSX({
resolveLens: true
});
const sessionWithLensData = ssx.signIn();
const ssx = new SSX({
resolveLens: 'onServer'
});
const sessionWithLensData = ssx.signIn();
SSX enables developers to configure the fields of their Sign-in with Ethereum (SIWE) message using the
siweConfig option. This option allows you to overwrite the fields found in the SIWE message. This option allows you to create SIWE messages that may not be valid in specific environments, so use this option carefully.siweConfig: {
address?: string;
chainId?: string;
domain?: string;
nonce?: string;
issuedAt?: string;
expirationTime?: string;
requestId?: string;
notBefore?: string;
resources?: Array<string>;
statement?: string;
};
Here is an example of how you use it:
const ssx = new SSX({
siweConfig: {
statement: 'Sign in to use our service today!',
requestId: 'unique-id-for-specific-purpose',
},
});
Last modified 4mo ago