๐ชAccess Tokens
Access tokens represent a secure and credible verification of wallet and/or token ownership that can be leveraged repeatedly without additional user interaction until expiration.
Last updated
Access tokens represent a secure and credible verification of wallet and/or token ownership that can be leveraged repeatedly without additional user interaction until expiration.
Last updated
Access tokens represent a secure and credible verification of wallet and/or token ownership that can be leveraged repeatedly without additional user interaction until expiration.
Atrribute | Description |
---|---|
Access tokens are returned after a successful auth flow, which is usually initiated by picket.login
. An access token is valid until its expiration timestamp (exp
). Once an access token expires, the user will have to re-login to get a new one.
Remember, an access token is a secret. Never share an access token with anyone!
Once a user is logged in, you'll get their access token as part of the response from picket.login
. If you are using a Picket client-side SDK, the user's access token will be saved to the browser's local storage and can be access as part of the SDK's auth state.
Get the access token from the auth state once the user is logged in
Access tokens are used in JWT-based authentication to allow an application to access an API. To include an access token (JWT) in a request, send it as a Bearer Token in the HTTP Authorization header.
Once a backend receives an access token in the authorization header, it should parse the header and validate the access token. After validating, the backend can trust that the request came from the associated wallet address!
The simplest way to validate an access token is to leverage Picket's /auth/validate
endpoint; however, you can also validate access token manually.
This section gets into the weeds for those who want it. For the easiest and fastest way to validate JWTs, we recommend using our validate endpoint to validate JWTs server-side which handles this all for you in a single api call.
The process for validating any JWT is as follows
Check the JWT is well-formed. This can be done without knowing the encryption method or signing key
Check the signature. This requires fetching the corresponding public key from Pickets' JSON Web Keys (JWKs) endpoint (/.well-known/jwks.json).
Check the standard claims
The issuer iss
equals picketapi.com
Check that the JWT hasn't expired. The expiration time exp
must be later than (>) the current unix timestamp
For more details on how to do this, we recommend Auth0's documentation on this standard process.
aud
) claimOnce you performed the standard JWT validation, you'll have the decoded JWT. With the decoded JWT, you'll want to verify that the aud
equals your Picket project ID. This prevents other people from using a different an access token from another Picket-powered application.
If this is a token-gated API, you'll need to verify the access token meets the requirements.
chain
The blockchain for this token
walletAddress
The wallet address for this token
displayAddress
The ENS name for the wallet address if it exists; otherwise, the wallet address
contractAddress
The token contract address associated with this access token (Optional). This will only be part of the token if it is a requirement in the auth request
tokenBalance
The token balance held by the wallet address for the contract address at the time the token was issued (Optional). This will only be part of the token if it is a requirement in the auth request.
tokenIds
The token IDs address associated with this access token (Optional). This will only be part of the token if it is a requirement in the auth request.
iat
Issued at timestamp (UTC in seconds).
ext
Expiration timestamp (UTC in seconds). The default expiration is 12 hours.
iss
The issuer, or signer. This will always be Picket's API (https://picketapi.com)
sub
The "subject" of the request. This field is populated with the blockchain associated with this token and the user's wallet address
aud
Identifies the project space. This field is populated with the Picket project ID
ver
The version of Picket API used to generate the token
tid
Unique token identifier
email
An auto-generated web3 email for the user based off their wallet address. There is no guarantee the user will check this inbox.
If you want an email for your users, you should collect it manually.