Amplify has re-imagined the way frontend developers build fullstack applications. Develop and deploy without the hassle.

Page updated May 2, 2024

With admin actions

Amplify Auth can be managed with the AWS SDK's @aws-sdk/client-cognito-identity-provider package. This package is intended to use server-side, and can be used within a Function. This example focuses on the addUserToGroup action and will be defined as a custom mutation.

To get started, create an "ADMINS" group that will be used to authorize the mutation:

import { defineAuth } from "@aws-amplify/backend"
export const auth = defineAuth({
loginWith: {
email: true,
groups: ["ADMINS"]

Next, create the Function resource:

import { defineFunction } from "@aws-amplify/backend"
export const addUserToGroup = defineFunction({
name: "add-user-to-group",

Then, in your auth resources, grant access for the function to perform the addUserToGroup action. Learn more about granting access to auth resources.

import { defineAuth } from "@aws-amplify/backend"
import { addUserToGroup } from "../data/add-user-to-group/resource"
export const auth = defineAuth({
loginWith: {
email: true,
groups: ["ADMINS"],
access: (allow) => [

You're now ready to define the custom mutation. Here you will use the newly-created addUserToGroup function resource to handle the addUserToGroup mutation. This mutation can only be called by a user in the "ADMINS" group.

import type { ClientSchema } from "@aws-amplify/backend"
import { a, defineData } from "@aws-amplify/backend"
import { addUserToGroup } from "./resource"
const schema = a.schema({
addUserToGroup: a
userId: a.string().required(),
groupName: a.string().required(),
.authorization((allow) => ["ADMINS")])
export type Schema = ClientSchema<typeof schema>
export const data = defineData({
authorizationModes: {
defaultAuthorizationMode: "iam",

Lastly, create the function's handler using the exported client schema to type the handler function, and the generated env to specify the user pool ID you'd like to interact with:

import type { Schema } from "../resource"
import { env } from "$amplify/env/add-user-to-group"
import {
} from "@aws-sdk/client-cognito-identity-provider"
type Handler = Schema["addUserToGroup"]["functionHandler"]
const client = new CognitoIdentityProviderClient()
export const handler: Handler = async (event) => {
const { userId, groupName } = event.arguments
const command = new AdminAddUserToGroupCommand({
Username: userId,
GroupName: groupName,
const response = await client.send(command)
return response

In your frontend, use the generated client to call your mutation using the group name and the user's ID.

import type { Schema } from "../amplify/data/resource"
import { generateClient } from "aws-amplify/data"
const client = generateClient<Schema>()
await client.mutations.addUserToGroup({
groupName: "ADMINS",
userId: "5468d468-4061-70ed-8870-45c766d26225",