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

Choose your framework/language

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",