Javascript Library - picket-js
Getting started with picket-js
npm install --save "@picketapi/picket-js"
The Picket constructor creates a new instance of the Picket class. It takes a publishable API key as a parameter.
import Picket from "@picketapi/picket-js";
const picket = new Picket("YOUR_PUBLISHABLE_KEY_HERE");
We’ve placed a placeholder publishable API key in this example. Replace it with your actual publishable API key.
import Picket from "@picketapi/picket-js";
const picket = new Picket("YOUR_PUBLISHABLE_KEY_HERE");
const { accessToken, user } = await picket.login();
login
optionally takes in token ownership requirements parameter. You can use this if you only want to allow users to login if they have a specific token, commonly referred to as token gating.login
is the easiest way to use Picket with your web, mobile, or native application. This enables you to securely login users via their wallet with a single line of code. Ethereum (Mainnet)
Solana
// default chain is Ethereum
const { user } = await picket.login();
// or specifiy it explicitly
const { user } = await picket.login({ chain: "ethereum" });
const { user } = await picket.login({ chain: "solana" });
EVM-Compatible Chains
Solana
await picket.login({
// any supported EVM-compatible chain
// if omitted, defaults to "ethereum"
chain: "ethereum",
// restrict access to token holders
contractAddress: "0xCONTRACT_ADDRESS",
// omit if any number of tokens are acceptable
minTokenBalance: 1
});
await picket.login({
chain: "solana",
// Replace this the tokens you want to verify ownership for
// the token ID is the mint associated with a SPL token
// user needs to own the minTokenBalance of at least one of the listed token
tokenIds: ["78AZe2223PknLYT9mn2VCJPAsdvuB6LzFAhgQeVoxddW", "2dQG4YYunFrbJjzW6UTcUmePs8UDy5jz43H6uSCZSAcS"],
// Replace with minimum balance you want to verify users' currently hold across all token IDs,
// or omit if any number of tokens is sufficient
minTokenBalance: 1
});
logout
deletes the cached user's access token. await picket.logout();
authState
returns the user's current authorization state. If the user is logged in, this includes the user's
accessToken
and information. If the user is logged out, the authState
will be null. // assumes user is logged in
const { accessToken, user } = await picket.authState();
isCurrentUserAuthorized
checks if the currently logged in user meets the given authorization requirements. This is commonly used for implementing incremental auth.const allowed = await picket.isCurrentUserAuthorized({
// pass in authorization requirements
requirements: {
contractAddresss: "0xCONTRACT",
},
});
On success,
isCurrentUserAuthorized
will update the user's access token. The updated access token contains the user's related token balances, so all future calls isCurrentUserAuthorized
will return true. Once a user is logged out or their session expires, their cached token balances will be cleared.By default, all calls to
isCurrentUserAuthorized
check the user's access token token balances before re-fetching their balances from the blockchain. This avoids unnecessary network I/O and keeps the user experience as snappy as possible. If you know the user's related token balances have changed, you can force Picket to re-fetch their information via the
revalidation
parameterconst allowed = await picket.isCurrentUserAuthorized({
// pass in authorization requirements
requirements: {
contractAddresss: "0xCONTRACT",
},
// do not use cache when checking the user's token balances
revalidate: true,
});
connect
is a convenience function for connecting to a wallet provider with the user-friendly Picket connect modal Ethereum
Solana
// Ethereum is the default chain
const { walletAddress, signature, provider } = await picket.connect();
// it can also be passed in explicitly
const { walletAddress, signature, provider } = await picket.connect({ chain: "ethereum" });
const { walletAddress, signature, provider } = await picket.connect({ chain: "solana" });
A
nonce
is random value generated by the Picket API to that user must sign to prove ownership a wallet address. The login
function handles nonce
generation and signature verification for you. You'll only need to use nonce
if you'd like to implement your own wallet authentication flow. A
nonce
is unique to a project and wallet address. If a nonce
doesn't exist for the project and wallet address, Picket will generate a new nonce
; otherwise, Picket will return the existing nonce. A nonce
is valid for two minutes before self-destructing.const { nonce, statement, format } = await picket.nonce({
chain: "ethereum",
walletAddress: "0x_WALLET_ADDRESS",
});
nonce
takes in an optional locale
parameter, which is used to localize the signing message statement in to the given locale
. When using the login
function from picket-js
or picket-react
, the user's browser locale will automatically be passed as the locale
for the signing message statement.Language Codes
const { nonce, statement, format } = await picket.nonce({
chain: "ethereum",
walletAddress: "0x_WALLET_ADDRESS",
// translate the statement to Afrikaans
locale: "af",
});
validate
validates an access token. This is helpful to ensure that cached local token is still valid when the app loads. The picket-js
library automatically validates access tokens when they are loaded from the local storage cache. If the access token is valid,
validate
returns the decoded claims of the access token.const payload = await picket.validate("ACCESS_TOKEN");
const payload = await picket.validate("ACCESS_TOKEN", {
// pass the authorization requirements
contractAddress: "0xCONTRACT_ADDRESS",
minTokenBalance: 1,
});
The Picket Login Modal supports several themes. By default the login modal will use the
light
theme. However, you can set it to a different theme to best fit into your overall web experience.You can set the theme when instantiating Picket:
const picket = new Picket("YOUR_PUBLISHABLE_KEY_HERE", {
theme: "dark",
});
picket.loginWithRedirect
implements the PKCE flow. In this flow the user is redirected back to a whitelisted redirect URI after authentication, so there are two steps the process 1) authenticate the user 2) handle the login redirect, also known as the login callback.EVM
Solana
import { defaultLoginRedirectCallback } from "@picketapi/picket-js";
// login will redirect user to Picket authorization server
document.getElementById("login").addEventListener("click", async () => {
try {
await picket.loginWithRedirect();
} catch (err) {
console.log("failed to login", err)
}
});
// in your callback route (defaults to the same route as your login page)
window.addEventListener("load", async () => {
try {
const { appState } = await picket.handleLoginRedirect();
defaultLoginRedirectCallback(appState);
}
// if successful, get user info and access token
const { accessToken, user } = await picket.authState();
console.log(user);
});
import { defaultLoginRedirectCallback } from "@picketapi/picket-js";
// login will redirect user to Picket authorization server
document.getElementById("login").addEventListener("click", async () => {
try {
await picket.loginWithRedirect({ chain: "solana" });
} catch (err) {
console.log("failed to login", err)
}
});
// in your callback route (defaults to the same route as your login page)
window.addEventListener("load", async () => {
try {
const { appState } = await picket.handleLoginRedirect();
defaultLoginRedirectCallback(appState);
}
// if successful, get user info and access token
const { accessToken, user } = await picket.authState();
console.log(user);
});
By default,
picket.loginWithRedirect
will redirect back to the same location (window.location.href
) as the initial login request. If you'd like your user to be redirected to a different page, you can pass in additional optionsEVM
Solana
await picket.loginWithRedirect({
// restrict access to token holders
contractAddress: "0xCONTRACT_ADDRESS",
minTokenBalance: 1
}, {
// change redirect location
redirectURI: "https://my-app.com/login/callback",
});
await picket.loginWithRedirect({
// restrict access to token holders
tokenIds: ["TOKEN_ID_MINT"],
minTokenBalance: 1
}, {
// change redirect location
redirectURI: "https://my-app.com/login/callback",
});
Popup windows are often blocked by browsers. For a consistent user experience, prefer
login
or loginWithRedirect
picket.loginWithPopup
is an alternative implementation of the PKCE flow that uses a popup rather than a redirect to securely authenticate users. The lack of redirects is convenient from a user experience perspective, but popups are often blocked by browsers, especially on mobile browsers. If you use this method, warn your users to enable popups on their browser if the flow fails.EVM
Solana
await picket.loginWithPopup({
// restrict access to token holders
contractAddress: "0xCONTRACT_ADDRESS",
minTokenBalance: 1
});
await picket.loginWithPopup({
// restrict access to token holders
tokenIds: ["TOKEN_ID_MINT"],
minTokenBalance: 1
});
Last modified 7mo ago