Cognito Basics

Seven examples to get you started with Amazon Cognito User Pools via SDK - five basic and two intermediate.

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3), using the cognito-idp service (Cognito Identity Provider).

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-cognito-identity-provider (Node.js 18+).
An AWS account and a default region configured, since user pools are regional resources.
IAM permissions for cognito-idp:* actions used below, scoped to the pools you manage.

Basic Examples

1. Create a User Pool

A user pool is the managed directory that stores your users and runs sign-up/sign-in.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
pool = cognito.create_user_pool(
    PoolName="acme-app-users",
    AutoVerifiedAttributes=["email"],
)
print(pool["UserPool"]["Id"])   # e.g. us-east-1_AbC123xyz

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, CreateUserPoolCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
const pool = await cognito.send(new CreateUserPoolCommand({
  PoolName: "acme-app-users",
  AutoVerifiedAttributes: ["email"],
}));
console.log(pool.UserPool?.Id);

AutoVerifiedAttributes tells Cognito to send a verification code and require it before an email/phone counts as confirmed.
The returned pool Id (e.g. us-east-1_AbC123xyz) is required by every other operation on this pool.
Password policy, MFA settings, and Lambda triggers can all be set here or updated later.
Creating a pool is a one-time setup step, not something your application does at runtime.

Related: Cognito's User Pool vs Identity Pool Split - what a user pool is for.

2. Create an App Client

An app client is the credential your application uses to talk to the pool.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
client = cognito.create_user_pool_client(
    UserPoolId="us-east-1_AbC123xyz",
    ClientName="acme-web-app",
    ExplicitAuthFlows=["ALLOW_USER_PASSWORD_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"],
)
print(client["UserPoolClient"]["ClientId"])

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, CreateUserPoolClientCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
const client = await cognito.send(new CreateUserPoolClientCommand({
  UserPoolId: "us-east-1_AbC123xyz",
  ClientName: "acme-web-app",
  ExplicitAuthFlows: ["ALLOW_USER_PASSWORD_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"],
}));
console.log(client.UserPoolClient?.ClientId);

One pool commonly has multiple app clients - one per platform (web, mobile, backend).
ExplicitAuthFlows opts the client into specific sign-in flows; without it, InitiateAuth calls are rejected.
A public client (browser, mobile) should never receive a client secret; leave GenerateSecret unset.
The ClientId returned here is used on every SignUp and InitiateAuth call.

SignUp registers a new user and triggers a confirmation code.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
cognito.sign_up(
    ClientId="1a2b3c4d5e6f7g8h9i0j",
    Username="jane@example.com",
    Password="Str0ng!Passw0rd",
    UserAttributes=[{"Name": "email", "Value": "jane@example.com"}],
)

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, SignUpCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
await cognito.send(new SignUpCommand({
  ClientId: "1a2b3c4d5e6f7g8h9i0j",
  Username: "jane@example.com",
  Password: "Str0ng!Passw0rd",
  UserAttributes: [{ Name: "email", Value: "jane@example.com" }],
}));

The new user is created in UNCONFIRMED status and cannot sign in yet.
Cognito emails or texts a confirmation code automatically based on the pool's verification settings.
Password requirements come from the pool's password policy, set at pool creation.
SignUp is a public, unauthenticated call - it only needs the app client ID, not admin credentials.

ConfirmSignUp activates the account using the code the user received.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
cognito.confirm_sign_up(
    ClientId="1a2b3c4d5e6f7g8h9i0j",
    Username="jane@example.com",
    ConfirmationCode="123456",
)

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, ConfirmSignUpCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
await cognito.send(new ConfirmSignUpCommand({
  ClientId: "1a2b3c4d5e6f7g8h9i0j",
  Username: "jane@example.com",
  ConfirmationCode: "123456",
}));

On success, the user's status moves from UNCONFIRMED to CONFIRMED.
An expired or wrong code raises ExpiredCodeException or CodeMismatchException - your UI should let the user request a new code.
Backend/admin flows can skip this using AdminConfirmSignUp with elevated IAM permissions instead.
Only a confirmed user can complete InitiateAuth sign-in.

InitiateAuth with USER_PASSWORD_AUTH exchanges a username and password for JWTs.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
resp = cognito.initiate_auth(
    ClientId="1a2b3c4d5e6f7g8h9i0j",
    AuthFlow="USER_PASSWORD_AUTH",
    AuthParameters={"USERNAME": "jane@example.com", "PASSWORD": "Str0ng!Passw0rd"},
)
tokens = resp["AuthenticationResult"]
print(tokens["IdToken"][:20], "...")

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, InitiateAuthCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
const resp = await cognito.send(new InitiateAuthCommand({
  ClientId: "1a2b3c4d5e6f7g8h9i0j",
  AuthFlow: "USER_PASSWORD_AUTH",
  AuthParameters: { USERNAME: "jane@example.com", PASSWORD: "Str0ng!Passw0rd" },
}));
console.log(resp.AuthenticationResult?.IdToken?.slice(0, 20), "...");

A successful response includes IdToken, AccessToken, and RefreshToken under AuthenticationResult.
USER_PASSWORD_AUTH sends the password to Cognito over TLS; USER_SRP_AUTH is the alternative that never transmits the raw password.
If the pool requires MFA, this call returns a ChallengeName instead of tokens, and you must respond to the challenge next.
The app client must have ALLOW_USER_PASSWORD_AUTH enabled, or this call is rejected.

Related: User Pools: Sign-Up, Sign-In & MFA - the full lifecycle and MFA challenge flow.

Intermediate Examples

6. Read the Signed-In User's Attributes

GetUser returns the caller's own attributes using their access token - no admin rights required.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
user = cognito.get_user(AccessToken=access_token)
attrs = {a["Name"]: a["Value"] for a in user["UserAttributes"]}
print(user["Username"], attrs.get("email"))

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, GetUserCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
const user = await cognito.send(new GetUserCommand({ AccessToken: accessToken }));
const attrs = Object.fromEntries((user.UserAttributes ?? []).map((a) => [a.Name, a.Value]));
console.log(user.Username, attrs.email);

GetUser takes the access token, not the ID token - the two are not interchangeable.
This call needs no IAM permissions of its own; the access token itself is the authorization.
Use it to populate a profile screen without a separate admin-level lookup.
For looking up an arbitrary user by username as an admin, use AdminGetUser instead, which does require IAM permissions.

7. Sign Out Everywhere

GlobalSignOut revokes all of a user's issued tokens across every device.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
cognito.global_sign_out(AccessToken=access_token)

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, GlobalSignOutCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
await cognito.send(new GlobalSignOutCommand({ AccessToken: accessToken }));

After this call, every refresh token issued to that user stops working, forcing re-authentication on all devices.
The access and ID tokens already issued remain technically valid until they expire, since Cognito does not track individual JWTs - only refresh tokens are revoked.
For shorter blast radius after sign-out, keep access/ID token lifetimes short (minutes, not days).
An admin equivalent, AdminUserGlobalSignOut, lets a backend force sign-out without the user's own access token.

Related: Cognito via SDK Best Practices - token lifetime and MFA defaults.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3), using the cognito-idp service (Cognito Identity Provider).

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-cognito-identity-provider (Node.js 18+).
An AWS account and a default region configured, since user pools are regional resources.
IAM permissions for cognito-idp:* actions used below, scoped to the pools you manage.

Basic Examples

1. Create a User Pool

A user pool is the managed directory that stores your users and runs sign-up/sign-in.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
pool = cognito.create_user_pool(
    PoolName="acme-app-users",
    AutoVerifiedAttributes=["email"],
)
print(pool["UserPool"]["Id"])   # e.g. us-east-1_AbC123xyz

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, CreateUserPoolCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
const pool = await cognito.send(new CreateUserPoolCommand({
  PoolName: "acme-app-users",
  AutoVerifiedAttributes: ["email"],
}));
console.log(pool.UserPool?.Id);

AutoVerifiedAttributes tells Cognito to send a verification code and require it before an email/phone counts as confirmed.
The returned pool Id (e.g. us-east-1_AbC123xyz) is required by every other operation on this pool.
Password policy, MFA settings, and Lambda triggers can all be set here or updated later.
Creating a pool is a one-time setup step, not something your application does at runtime.

Related: Cognito's User Pool vs Identity Pool Split - what a user pool is for.

2. Create an App Client

An app client is the credential your application uses to talk to the pool.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
client = cognito.create_user_pool_client(
    UserPoolId="us-east-1_AbC123xyz",
    ClientName="acme-web-app",
    ExplicitAuthFlows=["ALLOW_USER_PASSWORD_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"],
)
print(client["UserPoolClient"]["ClientId"])

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, CreateUserPoolClientCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
const client = await cognito.send(new CreateUserPoolClientCommand({
  UserPoolId: "us-east-1_AbC123xyz",
  ClientName: "acme-web-app",
  ExplicitAuthFlows: ["ALLOW_USER_PASSWORD_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"],
}));
console.log(client.UserPoolClient?.ClientId);

One pool commonly has multiple app clients - one per platform (web, mobile, backend).
ExplicitAuthFlows opts the client into specific sign-in flows; without it, InitiateAuth calls are rejected.
A public client (browser, mobile) should never receive a client secret; leave GenerateSecret unset.
The ClientId returned here is used on every SignUp and InitiateAuth call.

SignUp registers a new user and triggers a confirmation code.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
cognito.sign_up(
    ClientId="1a2b3c4d5e6f7g8h9i0j",
    Username="jane@example.com",
    Password="Str0ng!Passw0rd",
    UserAttributes=[{"Name": "email", "Value": "jane@example.com"}],
)

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, SignUpCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
await cognito.send(new SignUpCommand({
  ClientId: "1a2b3c4d5e6f7g8h9i0j",
  Username: "jane@example.com",
  Password: "Str0ng!Passw0rd",
  UserAttributes: [{ Name: "email", Value: "jane@example.com" }],
}));

The new user is created in UNCONFIRMED status and cannot sign in yet.
Cognito emails or texts a confirmation code automatically based on the pool's verification settings.
Password requirements come from the pool's password policy, set at pool creation.
SignUp is a public, unauthenticated call - it only needs the app client ID, not admin credentials.

ConfirmSignUp activates the account using the code the user received.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
cognito.confirm_sign_up(
    ClientId="1a2b3c4d5e6f7g8h9i0j",
    Username="jane@example.com",
    ConfirmationCode="123456",
)

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, ConfirmSignUpCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
await cognito.send(new ConfirmSignUpCommand({
  ClientId: "1a2b3c4d5e6f7g8h9i0j",
  Username: "jane@example.com",
  ConfirmationCode: "123456",
}));

On success, the user's status moves from UNCONFIRMED to CONFIRMED.
An expired or wrong code raises ExpiredCodeException or CodeMismatchException - your UI should let the user request a new code.
Backend/admin flows can skip this using AdminConfirmSignUp with elevated IAM permissions instead.
Only a confirmed user can complete InitiateAuth sign-in.

InitiateAuth with USER_PASSWORD_AUTH exchanges a username and password for JWTs.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
resp = cognito.initiate_auth(
    ClientId="1a2b3c4d5e6f7g8h9i0j",
    AuthFlow="USER_PASSWORD_AUTH",
    AuthParameters={"USERNAME": "jane@example.com", "PASSWORD": "Str0ng!Passw0rd"},
)
tokens = resp["AuthenticationResult"]
print(tokens["IdToken"][:20], "...")

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, InitiateAuthCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
const resp = await cognito.send(new InitiateAuthCommand({
  ClientId: "1a2b3c4d5e6f7g8h9i0j",
  AuthFlow: "USER_PASSWORD_AUTH",
  AuthParameters: { USERNAME: "jane@example.com", PASSWORD: "Str0ng!Passw0rd" },
}));
console.log(resp.AuthenticationResult?.IdToken?.slice(0, 20), "...");

A successful response includes IdToken, AccessToken, and RefreshToken under AuthenticationResult.
USER_PASSWORD_AUTH sends the password to Cognito over TLS; USER_SRP_AUTH is the alternative that never transmits the raw password.
If the pool requires MFA, this call returns a ChallengeName instead of tokens, and you must respond to the challenge next.
The app client must have ALLOW_USER_PASSWORD_AUTH enabled, or this call is rejected.

Related: User Pools: Sign-Up, Sign-In & MFA - the full lifecycle and MFA challenge flow.

Intermediate Examples

6. Read the Signed-In User's Attributes

GetUser returns the caller's own attributes using their access token - no admin rights required.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
user = cognito.get_user(AccessToken=access_token)
attrs = {a["Name"]: a["Value"] for a in user["UserAttributes"]}
print(user["Username"], attrs.get("email"))

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, GetUserCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
const user = await cognito.send(new GetUserCommand({ AccessToken: accessToken }));
const attrs = Object.fromEntries((user.UserAttributes ?? []).map((a) => [a.Name, a.Value]));
console.log(user.Username, attrs.email);

GetUser takes the access token, not the ID token - the two are not interchangeable.
This call needs no IAM permissions of its own; the access token itself is the authorization.
Use it to populate a profile screen without a separate admin-level lookup.
For looking up an arbitrary user by username as an admin, use AdminGetUser instead, which does require IAM permissions.

7. Sign Out Everywhere

GlobalSignOut revokes all of a user's issued tokens across every device.

# --- Python (boto3) ---
import boto3
 
cognito = boto3.client("cognito-idp")
 
cognito.global_sign_out(AccessToken=access_token)

// --- TypeScript (AWS SDK v3) ---
import { CognitoIdentityProviderClient, GlobalSignOutCommand } from "@aws-sdk/client-cognito-identity-provider";
 
const cognito = new CognitoIdentityProviderClient({});
 
await cognito.send(new GlobalSignOutCommand({ AccessToken: accessToken }));

After this call, every refresh token issued to that user stops working, forcing re-authentication on all devices.
The access and ID tokens already issued remain technically valid until they expire, since Cognito does not track individual JWTs - only refresh tokens are revoked.
For shorter blast radius after sign-out, keep access/ID token lifetimes short (minutes, not days).
An admin equivalent, AdminUserGlobalSignOut, lets a backend force sign-out without the user's own access token.

Related: Cognito via SDK Best Practices - token lifetime and MFA defaults.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Cognito Basics

Buscar en la documentación

Cognito Basics