Skip to main content

Wallet Authenticator

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

The wallet authenticator enables server-side applications to securely identify the connected wallet address of users on the client-side, and also enables users to authenticate to any backend using just their wallet. It implements the JSON Web Token (JWT) authentication standard.

# We specify the domain of the application to authenticate to
domain = "example.com"

# We can then generate a payload for the connected wallet to login
# This can also be done on the client side with the thirdweb TypeScript SDK
payload = sdk.auth.login(domain)

# Then, on the server, we can securely verify the connected address that signed the payload
address = sdk.auth.verify(domain, payload)

# And we can also generate an authentication token to send back to the original payload sender
token = sdk.auth.generate_auth_token(domain, payload)

# Finally, the token can be use dby the original payload sender to authenticate to the backend
# And the server can use the following function to authenticate the token and verify the address
address = sdk.auth.authenticate(domain, token)

login​

A client-side function that allows the connected wallet to login to a server-side application.

Generates a login payload that can be sent to the server-side for verification or authentication.

# Add the domain of the application that you want to log in to
domain = "example.com"

# Generate a signed login payload for the connected wallet to authenticate with
payload = sdk.auth.login(domain)
Configuration

domain​

The domain of the application that you want to log in to. Must be of type str.

options (optional)​

The configuration options for the login payload. Must be a LoginOptions object:

class LoginOptions:
    nonce: Optional[str] = None
    expiration_time: Optional[datetime] = None
    chain_id: Optional[int] = None

Return Value​

A LoginPayload object that can be sent to the server-side for verification or authentication.

class LoginPayload:
    payload: LoginPayloadData
    signature: str

class LoginPayloadData:
    domain: str
    address: str
    nonce: str
    expiration_time: datetime
    chain_id: Optional[int] = None

verify​

Server-side function to securely verify the address of the logged in client-side wallet

by validating the provided client-side login request.

domain = "example.com"
payload = sdk.auth.login(domain)

# Verify the login request
address = sdk.auth.verify(domain, payload)
Configuration

domain​

The domain of the application to verify the login request for. Must of of type str

payload​

The login payload to verify. Must be a LoginPayload object

class LoginPayload:
    payload: LoginPayloadData
    signature: str

class LoginPayloadData:
    domain: str
    address: str
    nonce: str
    expiration_time: datetime
    chain_id: Optional[int] = None

Return Value​

Returns the address of the logged in wallet that signed the payload as a str type.

generate_auth_token​

Server-side function that generates a JWT token from the provided login request that the

client-side wallet can use to authenticate to the server-side application.

domain = "example.com"
payload = sdk.auth.login(domain)

# Generate an authentication token for the logged in wallet
token = sdk.auth.generate_auth_token(domain, payload)
Configuration

domain​

The domain of the application to authenticate to. Must be of type str.

payload​

The login payload to authenticate with. Must be a LoginPayload object:

class LoginPayload:
    payload: LoginPayloadData
    signature: str

class LoginPayloadData:
    domain: str
    address: str
    nonce: str
    expiration_time: datetime
    chain_id: Optional[int] = None

options (optional)​

The configuration options for the authentication token. Must be an AuthenticationOptions object:

class AuthenticationOptions:
    invalid_before: Optional[datetime] = None
    expiration_time: Optional[datetime] = None

Return Value​

Returns an authentication token string that can be used to make authenticated requests to the server.

authenticate​

Server-side function that authenticates the provided JWT token. This function verifies that

the provided authentication token is valid and returns the address of the authenticated wallet.

domain = "example.com"
payload = sdk.auth.login(domain)
token = sdk.auth.generate_auth_token(domain, payload)

# Authenticate the token and get the address of the authenticating wallet
address = sdk.auth.authenticate(domain, token)
Configuration

domain​

The domain of the application to authenticate the token to. Must be of type str.

token​

The authentication token to authenticate with. Must be of type str.

Return Value​

A string representing the address of the authenticated wallet.