Authentication

The SDK requires users to be authenticated for all interactions with our MPC backend. We provide two methods: Coinbase Managed and Developer Managed authentication.

Coinbase Managed Auth

Coinbase Managed Authentication provides the fastest setup and leverages Coinbase's authentication. In this configuration, Coinbase authorizes the user via a login prompt that allows signing in with various methods.

Setup

Make sure that you've set up your project in CDP portal. You'll need to provide:

• Your dapp's name (no longer than 32 characters)
• A URL to your dapp's primary logo (PNG preferred, smaller than 100X100)
• A URL to your dapp's favicon.

You can edit this under the "Coinbase Managed Authentication" section of the CDP portal.

info

Our login UI heavily caches resources, so you might need to clear your browser cache or perform a force refresh (Cmd+ShiftR) to see your updates.

Example

Login your user by invoking the login() method with no arguments.

React

import { useWalletContext } from "@coinbase/waas-sdk-web-react";

const LoginButton = () => {
    const {waas, user} = useWalletContext();
    // this button triggers the login popup, which allows your user to identify themselves.
    return <button disabled={user || !waas} onClick={() => async () => waas!.login()}>Login</button>
}

Pure JS

if (!waas.auth.user) {
    const user = await waas.auth.login(); // NOTE: `waas` was previously returned from `await InitializeWaas(...)`
}

Developer Managed Auth

Use Developer Managed Authentication if you have an existing authentication system, or want to completely customize the login UX for your users. In this configuration, your backend issues a token which authorizes the current user to access their wallet.

1. Identify your user to obtain their wallet. If your user is already logged in, their session resumes automatically if the page is refreshed.

2. Generate a token for the Embedded Wallet SDK to authenticate users to the Coinbase backend. You must add an authenticated API to your backend to generate these tokens.

3. Configure the login method of our SDK with a callback to call this API. The login method automatically handles refreshing this token (by invoking this callback) when necessary.

Setup

1. Create a CDP API key on the CDP platform.

2. Install our backend authentication library:

npm install @coinbase/waas-server-auth

2. After identifying your user, expose an endpoint that issues the user a CDP token from the API key generated in step 1. Typically you pass your user's UUID into issueUserToken to issue the token.

   info

   Identify your user with a valid UUID. If you're using an integer ID, you can generate a deterministic UUID from your own ID (node example).

   For example, this handler /auth/token signs a token based on the supplied user_id. In a real world setting, you want to get your user_id from your session management system.

3. Securely store your API key and use mechanisms like environment variables to avoid committing secrets.

import { issueUserToken } from "@coinbase/waas-server-auth";
...

// Example Express Route for Token Issuance
app.post("/auth/token", async (req, res) => {
    // Assuming you already have your own auth system, you should have some logged in user session (e.g req.session)
    // Grab the user ID from there, and convert it to a valid UUID.
    const userId = "dbd016b0-960e-45c7-98c9-90cee794e744"; // TODO: get your user's UUID from your session!

    const { ttl: ttlSeconds, prod } = req.body;

    if (!userID) {
        res.json({ success: false, error: "the `user_id` field must be set" });
    }
    const apiKeyName = process.env.COINBASE_API_KEY_NAME; // "name" field of API key.
    const privateKey = process.env.COINBASE_API_PRIVATE_KEY; // "privateKey" field of API key.

    try {
        // Issuing a user token:
        const token = await issueUserToken({
            apiKeyName: apiKeyName,
            privateKey: privateKey,
            userID: userId,
        });
        res.json({ success: true, token });
    } catch (err: any) {
        res.json({ success: false, error: err.message });
    }
});

4. On the frontend, provide the provideAuthToken callback to the login() function.

   Your provideAuthToken should return the contents of a valid token as issued by @coinbase/waas-server-auth's issueUserToken function.

info

NOTE: With developer managed auth, you need to call .login({provideAuthToken}) on every page load, even if your user has already logged in. If you don't do this, it will appear that your user has logged out on refresh.

Example

In the example below, we implement provideAuthToken by calling our /auth/token endpoint.

React

import { useWalletContext } from "@coinbase/waas-sdk-web-react";

const App = () => {
    const {waas, user} = useWalletContext();
    // this button triggers a call to your authorization endpoint, which has previously identified your user
    // and can issue a token.
    // the next time this component re-renders, (and on page refreshes), you need to invoke
    // `login()` again, to tell Waas how to refresh your auth token (should it expire)
    return <button disabled={!!user || !waas} onClick={() => async () => waas!.login({
        provideAuthToken: async () => {
            // call your backend endpoint /auth/token that invokes `issueUserToken`
            const tokenResponse = await fetch("/auth/token", { method: 'POST'}).then(r => r.json())
            return tokenResponse.token;
        }
    })}></button>
}

Pure JS

if (!waas.auth.user) {
    const user = await waas.auth.login({
        provideAuthToken: async () => {
            // call your backend endpoint /auth/token that invokes `issueUserToken`
            const tokenResponse = await fetch("/auth/token", { method: 'POST'}).then(r => r.json())
            return tokenResponse.token;
        }
    }); // NOTE: `waas` was previously returned from `await InitializeWaas(...)`
}