Looking for how to use this in your app?See Frontend Libraries →

Use BasicAuth with an Amplify backend

This guide secures your Blocks API with the AWS Blocks AuthBasic Block — simple username and password authentication with JWT sessions.

For production apps, authenticate your Blocks API with your existing Amplify Cognito user pool — see Connect your frontend. AuthBasic is a good fit for prototypes, internal tools, and MVPs where you want lightweight auth on the Blocks portion of your app without configuring Cognito. It does not replace Amplify Auth.

This guide assumes you have already added AWS Blocks to your Amplify project.

Install the AuthBasic Block

Add the Block to your aws-blocks workspace:

npm install @aws-blocks/bb-auth-basic

Define authentication

In aws-blocks/index.ts, create an AuthBasic instance, protect your API methods with requireAuth, and export the authentication API the frontend uses to sign users in and out:

aws-blocks/index.ts
import { ApiNamespace, Scope } from '@aws-blocks/blocks';
import { AuthBasic } from '@aws-blocks/bb-auth-basic';
const scope = new Scope('my-app');
const auth = new AuthBasic(scope, 'auth', {
  sessionDuration: 86400, // 24 hours
  passwordPolicy: { minLength: 8, requireDigits: true }
export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getProfile() {
    const user = await auth.requireAuth(context);
    return { username: user.username, createdAt: user.createdAt };
// Export the auth API for the frontend sign-in / sign-up flows
export const authApi = auth.createApi();

requireAuth(context) returns the signed-in user or throws a 401 (SessionExpiredException). AuthBasic manages the session with an HTTP cookie, so there is no token to attach manually.

Deploy

Deploy with the rest of your backend:

npm run sandbox

Sign users in from your frontend

Regenerate the typed client so it includes both api and authApi:

npm run blocks:generate-client

Drive the sign-up and sign-in flows through the setAuthState action on authApi. Each action is a single flat input — { action, ...fields }:

import { api, authApi } from 'aws-blocks';
// Sign up (immediate, since no code delivery is configured)
await authApi.setAuthState({
  action: 'signUp',
  username: 'alice',
  password: 'hunter2!'
// Sign in — sets the session cookie
await authApi.setAuthState({
  action: 'signIn',
  username: 'alice',
  password: 'hunter2!'
// Authenticated calls now succeed
const profile = await api.getProfile();

Handle bad credentials with the Block's typed errors. setAuthState does not throw — it returns the new auth state with an errorName, so branch on it with hasAuthError:

import { hasAuthError } from '@aws-blocks/core';
import { AuthBasicErrors } from '@aws-blocks/bb-auth-basic';
const next = await authApi.setAuthState({
  action: 'signIn',
  username: 'alice',
  password: 'hunter2!'
if (hasAuthError(next, AuthBasicErrors.InvalidCredentials)) {
  // show "invalid username or password"

To require email confirmation, provide a codeDelivery callback. This puts new users in an unconfirmed state until they verify a 6-digit code, and enables password reset:

aws-blocks/index.ts
const auth = new AuthBasic(scope, 'auth', {
  passwordPolicy: { minLength: 8, requireDigits: true },
  codeDelivery: async (username, code) => {
    await sendEmail(username, `Your verification code: ${code}`);

You could deliver the code with the AWS Blocks EmailClient Block. Users then complete sign-up with { action: 'confirmSignUp', username, code, password }.

Next steps

Add an AI agent to your Amplify app.
See the AWS Blocks Developer Guide for the full AuthBasic API, including password reset and cross-domain sessions.