---
updatedAt: 2026-10-29T22:29:43.000Z
agentTools:
  siteIndex: https://techdocs.akamai.com/llms.txt
  projectIndex: https://techdocs.akamai.com/mfa/llms.txt
---

# Add a user

Create a new user.

# OpenAPI definition

```json
{
  "externalDocs": {
    "description": "See documentation for Akamai's Akamai MFA API",
    "url": "https://techdocs.akamai.com/mfa/reference"
  },
  "info": {
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "title": "Users",
    "version": "v1"
  },
  "openapi": "3.0.0",
  "paths": {
    "/users": {
      "post": {
        "description": "Create a new user.",
        "externalDocs": {
          "description": "See documentation for this operation in Akamai's Akamai MFA API",
          "url": "https://techdocs.akamai.com/mfa/reference/post-user"
        },
        "operationId": "post-user",
        "parameters": [
          {
            "description": "Unique identifier for the contract.",
            "in": "query",
            "name": "contractId",
            "required": true,
            "schema": {
              "example": "C-0N7RAC71",
              "type": "string"
            },
            "x-akamai": {
              "file-path": "parameters/contract-id-required.yaml"
            }
          },
          {
            "description": "For customers who manage more than one account, this [runs the operation from another account](https://techdocs.akamai.com/developer/docs/manage-many-accounts-with-one-api-client). The Identity and Access Management API provides a [list of available account switch keys](https://techdocs.akamai.com/iam-api/reference/get-client-account-switch-keys).",
            "in": "query",
            "name": "accountSwitchKey",
            "required": false,
            "schema": {
              "example": "1-5C0YLB:1-8BYUX",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "email": "afero@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "username": "szhang"
              },
              "schema": {
                "additionalProperties": false,
                "description": "Add user request JSON.",
                "properties": {
                  "email": {
                    "description": "The user's email address.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "firstName": {
                    "description": "The user's first name.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "lastName": {
                    "description": "The user's last name.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "username": {
                    "description": "The user's username. The username is unique for the tenant.",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "username"
                ],
                "type": "object",
                "x-akamai": {
                  "file-path": "schemas/add-user-request.yaml"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "aliases": [
                    {
                      "alias": "johndoe",
                      "aliasId": "alias_2DveJ9HKmURNmKrz3EOxWZ",
                      "createdDate": "2021-10-21T04:04:46.309+00:00",
                      "modifiedDate": "2021-10-21T04:04:46.309+00:00"
                    },
                    {
                      "alias": "john_doe",
                      "aliasId": "alias_6AWYrzkzVOfLPIF2iQRBFe",
                      "createdDate": "2021-10-21T04:04:46.505+00:00",
                      "modifiedDate": "2021-10-21T04:04:46.505+00:00"
                    }
                  ],
                  "createdDate": "2021-10-21T04:03:30.678+00:00",
                  "deviceCount": 1,
                  "email": "mrossi@example.com",
                  "firstName": "John",
                  "groups": [
                    {
                      "createdDate": "2021-10-21T04:03:30.678+00:00",
                      "groupId": "group_5PzsV2iwFgugE51YdbCPd9",
                      "groupName": "admins",
                      "modifiedDate": "2021-10-21T04:04:45.091+00:00",
                      "summary": "Group with admin access to acme resources"
                    },
                    {
                      "createdDate": "2021-10-21T04:03:30.678+00:00",
                      "groupId": "group_7AzsV2iwFgugE51YdbCPB9",
                      "groupName": "sales",
                      "modifiedDate": "2021-10-21T04:04:45.091+00:00",
                      "summary": "Group for Sales users"
                    }
                  ],
                  "importSource": {
                    "id": "scim_1787",
                    "type": "SCIM"
                  },
                  "lastName": "Doe",
                  "modifiedDate": "2021-10-21T04:04:45.091+00:00",
                  "userId": "user_2eVKpVVpgzM3fPWsao3sbh",
                  "userStatus": "ACTIVE",
                  "username": "asingh"
                },
                "schema": {
                  "additionalProperties": false,
                  "description": "Provides response data for a specific user.",
                  "properties": {
                    "aliases": {
                      "description": "The user's alternate names.",
                      "items": {
                        "additionalProperties": false,
                        "description": "Specifies details for a user's alias.",
                        "properties": {
                          "alias": {
                            "description": "Alternate usernames for the user.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "aliasId": {
                            "description": "A unique identifier for the user's alternate username.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "createdDate": {
                            "description": "ISO 8601 timestamp marking when the alias was created.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "modifiedDate": {
                            "description": "ISO 8601 timestamp marking when the alias was last modified.",
                            "format": "date-time",
                            "type": "string"
                          }
                        },
                        "required": [
                          "aliasId",
                          "alias",
                          "createdDate"
                        ],
                        "type": "object",
                        "x-akamai": {
                          "file-path": "schemas/user-alias.yaml"
                        }
                      },
                      "minItems": 0,
                      "type": "array"
                    },
                    "createdDate": {
                      "description": "ISO 8601 timestamp marking when the user account was created.",
                      "format": "date-time",
                      "type": "string"
                    },
                    "deviceCount": {
                      "description": "The number of authentication devices enrolled by the user in Akamai MFA. The user can enroll and use a set of authentication devices.",
                      "minimum": 0,
                      "type": "integer"
                    },
                    "devices": {
                      "description": "Authentication devices the user enrolled in Akamai MFA.",
                      "items": {
                        "additionalProperties": false,
                        "description": "Provides response data for a specific user device.",
                        "properties": {
                          "createdBy": {
                            "description": "This indicates who created the device. `EXTERNAL` means the device was created by an external identity provider. `ADMIN` means the device was created by an Akamai MFA administrator. `USER` indicates devices created by users themselves, for example, through self-enrollment.",
                            "enum": [
                              "EXTERNAL",
                              "ADMIN",
                              "USER"
                            ],
                            "type": "string"
                          },
                          "createdDate": {
                            "description": "ISO 8601 timestamp marking when the device was created.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "deviceId": {
                            "description": "Uniquely identifies the authentication device enrolled by the user.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "deviceName": {
                            "description": "A user-friendly name to identify the authentication device.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "deviceType": {
                            "description": "A user's type of authentication device. Refer to [API concepts](ref:mfa-concepts) to learn about device types.",
                            "enum": [
                              "AKAMAI_AUTHENTICATOR",
                              "PHONE_NUMBER",
                              "SECURITY_KEY",
                              "PLATFORM_AUTHENTICATOR",
                              "PASSKEY",
                              "GENERIC_WEBAUTHN",
                              "THIRD_PARTY_AUTHENTICATOR",
                              "HARDWARE_TOKEN",
                              "EMAIL_ADDRESS",
                              "BYPASS_CODE"
                            ],
                            "type": "string"
                          },
                          "isDeviceEnabled": {
                            "description": "Whether the authentication device is enabled in Akamai MFA. You can disable a user's device that remains inactive or poses a threat to your data. Users can't use a deactivated device to confirm their identity. Disabling a device is reversible, and isn't the same as permanently deleting a device. See [Enable a device](ref:post-enable-user-device) and [Disable a device](ref:post-disable-user-device) for details on how to manage user devices.",
                            "type": "boolean"
                          },
                          "isDeviceRecoverable": {
                            "description": "Whether the device that's been disabled can be recovered or reenabled.",
                            "type": "boolean"
                          },
                          "isRecoveryResyncEnabled": {
                            "default": false,
                            "description": "Whether the device is currently in recovery resync mode.",
                            "type": "boolean"
                          },
                          "modifiedDate": {
                            "description": "ISO 8601 timestamp marking when the device was last modified, or when it was last used since then.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "platform": {
                            "description": "The platform of the authentication device.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "status": {
                            "description": "This indicates the device's current status. See [API concepts](ref:mfa-concepts) to learn more about device statuses.",
                            "enum": [
                              "ENABLED",
                              "DELETED",
                              "DISABLED",
                              "DISABLED_UNRECOVERABLE"
                            ],
                            "type": "string"
                          }
                        },
                        "required": [
                          "deviceId",
                          "deviceType",
                          "platform",
                          "createdDate"
                        ],
                        "type": "object",
                        "x-akamai": {
                          "file-path": "schemas/device.yaml"
                        }
                      },
                      "minItems": 0,
                      "type": "array"
                    },
                    "email": {
                      "description": "The user's email address.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "firstName": {
                      "description": "The user's first name.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "groups": {
                      "description": "Lists the user's group memberships.",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "createdDate": {
                            "description": "Descriptive label for the group.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "groupId": {
                            "description": "Unique identifier for the group.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "groupName": {
                            "description": "Descriptive label for the group.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "modifiedDate": {
                            "description": "Descriptive label for the group.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "summary": {
                            "description": "Summary of the group. Indicates what the group represents.",
                            "minLength": 0,
                            "type": "string"
                          }
                        },
                        "required": [
                          "groupId",
                          "groupName"
                        ],
                        "type": "object",
                        "x-akamai": {
                          "file-path": "schemas/user-group.yaml"
                        }
                      },
                      "minItems": 0,
                      "type": "array"
                    },
                    "importSource": {
                      "additionalProperties": false,
                      "description": "The imported user's provisioning source. A `null` value marks manually imported users.",
                      "nullable": true,
                      "properties": {
                        "id": {
                          "description": "A unique identifier for the imported user's provisioning source.",
                          "minLength": 1,
                          "type": "string"
                        },
                        "type": {
                          "description": "The imported user's provisioning source, either `SCIM` or `EAA`.",
                          "enum": [
                            "SCIM",
                            "EAA"
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "type"
                      ],
                      "type": "object",
                      "x-akamai": {
                        "file-path": "schemas/user-source.yaml"
                      }
                    },
                    "lastName": {
                      "description": "The user's last name.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "modifiedDate": {
                      "description": "ISO 8601 timestamp marking when the user account was last modified.",
                      "format": "date-time",
                      "type": "string"
                    },
                    "userId": {
                      "description": "A unique identifier for each user account.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "userStatus": {
                      "description": "The status of the user account, either `ACTIVE`, `DEVICES_DISABLED`, `PROVISIONED`, `ADMIN_DISABLED`, `INACTIVE` or `PROVISIONING_DISABLED`. Refer to [API concepts](ref:mfa-concepts) to learn more about user account status.",
                      "enum": [
                        "ACTIVE",
                        "DEVICES_DISABLED",
                        "PROVISIONING_DISABLED",
                        "PROVISIONED",
                        "ADMIN_DISABLED",
                        "INACTIVE"
                      ],
                      "type": "string"
                    },
                    "username": {
                      "description": "The user's username. The username is unique for the tenant.",
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "userId",
                    "username",
                    "userStatus",
                    "deviceCount",
                    "createdDate"
                  ],
                  "type": "object",
                  "x-akamai": {
                    "file-path": "schemas/user-detail.yaml"
                  }
                }
              }
            },
            "description": "User successfully created."
          },
          "400": {
            "content": {
              "application/problem+json": {
                "example": {
                  "detail": "JSON Deserialization failure: 'alias: invalid type: null, expected a string at line 2 column 16'",
                  "instance": "84093d15-1fd0-421c-9182-8c873165ef58",
                  "title": "Bad Request",
                  "type": "https://problems.luna.akamaiapis.net/zt-mfa/bad-request"
                },
                "schema": {
                  "additionalProperties": false,
                  "description": "Represents error data in the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details format.",
                  "properties": {
                    "detail": {
                      "description": "Diagnostic instructions to locate and fix the problem.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "errors": {
                      "description": "For errors with more than one detected problem, this represents each as a nested Problem Details object.",
                      "items": {
                        "additionalProperties": false,
                        "description": "Represents error data in the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details format.",
                        "properties": {
                          "detail": {
                            "description": "Diagnostic instructions to locate and fix the problem.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "instance": {
                            "description": "Unique value generated with each API call.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "status": {
                            "description": "The HTTP status code that categorizes this error case.",
                            "maximum": 600,
                            "minimum": 100,
                            "type": "integer"
                          },
                          "title": {
                            "description": "A summary of each error case.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "type": {
                            "description": "Identifies each error case.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "type",
                          "title",
                          "detail"
                        ],
                        "type": "object",
                        "x-akamai": {
                          "file-path": "schemas/problem-nested.yaml"
                        }
                      },
                      "minItems": 0,
                      "type": "array",
                      "uniqueItems": true
                    },
                    "instance": {
                      "description": "Unique value generated with each API call.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "title": {
                      "description": "A summary of each error case.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "type": {
                      "description": "Identifies each error case.",
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "title",
                    "detail",
                    "instance"
                  ],
                  "type": "object",
                  "x-akamai": {
                    "file-path": "schemas/problem.yaml"
                  }
                }
              }
            },
            "description": "[Bad request](ref:400).",
            "x-akamai": {
              "file-path": "errors/400.yaml"
            }
          },
          "401": {
            "content": {
              "application/problem+json": {
                "example": {
                  "detail": "The request requires authentication.",
                  "instance": "84093d15-1fd0-421c-9182-8c873165ef58",
                  "title": "Unauthorized",
                  "type": "https://problems.luna.akamaiapis.net/zt-mfa/unauthorized"
                },
                "schema": {
                  "additionalProperties": false,
                  "description": "Represents error data in the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details format.",
                  "properties": {
                    "detail": {
                      "description": "Diagnostic instructions to locate and fix the problem.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "errors": {
                      "description": "For errors with more than one detected problem, this represents each as a nested Problem Details object.",
                      "items": {
                        "additionalProperties": false,
                        "description": "Represents error data in the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details format.",
                        "properties": {
                          "detail": {
                            "description": "Diagnostic instructions to locate and fix the problem.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "instance": {
                            "description": "Unique value generated with each API call.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "status": {
                            "description": "The HTTP status code that categorizes this error case.",
                            "maximum": 600,
                            "minimum": 100,
                            "type": "integer"
                          },
                          "title": {
                            "description": "A summary of each error case.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "type": {
                            "description": "Identifies each error case.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "type",
                          "title",
                          "detail"
                        ],
                        "type": "object",
                        "x-akamai": {
                          "file-path": "schemas/problem-nested.yaml"
                        }
                      },
                      "minItems": 0,
                      "type": "array",
                      "uniqueItems": true
                    },
                    "instance": {
                      "description": "Unique value generated with each API call.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "title": {
                      "description": "A summary of each error case.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "type": {
                      "description": "Identifies each error case.",
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "title",
                    "detail",
                    "instance"
                  ],
                  "type": "object",
                  "x-akamai": {
                    "file-path": "schemas/problem.yaml"
                  }
                }
              }
            },
            "description": "[Unauthorized](ref:401).",
            "x-akamai": {
              "file-path": "errors/401.yaml"
            }
          },
          "403": {
            "content": {
              "application/problem+json": {
                "example": {
                  "detail": "User does not have access.",
                  "instance": "84093d15-1fd0-421c-9182-8c873165ef58",
                  "title": "Forbidden",
                  "type": "https://problems.luna.akamaiapis.net/zt-mfa/forbidden"
                },
                "schema": {
                  "additionalProperties": false,
                  "description": "Represents error data in the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details format.",
                  "properties": {
                    "detail": {
                      "description": "Diagnostic instructions to locate and fix the problem.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "errors": {
                      "description": "For errors with more than one detected problem, this represents each as a nested Problem Details object.",
                      "items": {
                        "additionalProperties": false,
                        "description": "Represents error data in the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details format.",
                        "properties": {
                          "detail": {
                            "description": "Diagnostic instructions to locate and fix the problem.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "instance": {
                            "description": "Unique value generated with each API call.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "status": {
                            "description": "The HTTP status code that categorizes this error case.",
                            "maximum": 600,
                            "minimum": 100,
                            "type": "integer"
                          },
                          "title": {
                            "description": "A summary of each error case.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "type": {
                            "description": "Identifies each error case.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "type",
                          "title",
                          "detail"
                        ],
                        "type": "object",
                        "x-akamai": {
                          "file-path": "schemas/problem-nested.yaml"
                        }
                      },
                      "minItems": 0,
                      "type": "array",
                      "uniqueItems": true
                    },
                    "instance": {
                      "description": "Unique value generated with each API call.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "title": {
                      "description": "A summary of each error case.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "type": {
                      "description": "Identifies each error case.",
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "title",
                    "detail",
                    "instance"
                  ],
                  "type": "object",
                  "x-akamai": {
                    "file-path": "schemas/problem.yaml"
                  }
                }
              }
            },
            "description": "[Forbidden](ref:403).",
            "x-akamai": {
              "file-path": "errors/403.yaml"
            }
          },
          "500": {
            "content": {
              "application/problem+json": {
                "example": {
                  "detail": "Error in fetching policy details.",
                  "instance": "84093d15-1fd0-421c-9182-8c873165ef58",
                  "title": "Internal Server Error",
                  "type": "https://problems.luna.akamaiapis.net/zt-mfa/internal-server-error"
                },
                "schema": {
                  "additionalProperties": false,
                  "description": "Represents error data in the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details format.",
                  "properties": {
                    "detail": {
                      "description": "Diagnostic instructions to locate and fix the problem.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "errors": {
                      "description": "For errors with more than one detected problem, this represents each as a nested Problem Details object.",
                      "items": {
                        "additionalProperties": false,
                        "description": "Represents error data in the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details format.",
                        "properties": {
                          "detail": {
                            "description": "Diagnostic instructions to locate and fix the problem.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "instance": {
                            "description": "Unique value generated with each API call.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "status": {
                            "description": "The HTTP status code that categorizes this error case.",
                            "maximum": 600,
                            "minimum": 100,
                            "type": "integer"
                          },
                          "title": {
                            "description": "A summary of each error case.",
                            "minLength": 1,
                            "type": "string"
                          },
                          "type": {
                            "description": "Identifies each error case.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "type",
                          "title",
                          "detail"
                        ],
                        "type": "object",
                        "x-akamai": {
                          "file-path": "schemas/problem-nested.yaml"
                        }
                      },
                      "minItems": 0,
                      "type": "array",
                      "uniqueItems": true
                    },
                    "instance": {
                      "description": "Unique value generated with each API call.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "title": {
                      "description": "A summary of each error case.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "type": {
                      "description": "Identifies each error case.",
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "title",
                    "detail",
                    "instance"
                  ],
                  "type": "object",
                  "x-akamai": {
                    "file-path": "schemas/problem.yaml"
                  }
                }
              }
            },
            "description": "[Internal server error](ref:500).",
            "x-akamai": {
              "file-path": "errors/500.yaml"
            }
          }
        },
        "summary": "Add a user",
        "tags": [
          "Users"
        ]
      },
      "x-akamai": {
        "file-path": "paths/users.yaml",
        "path-info": "/users"
      }
    }
  },
  "servers": [
    {
      "url": "https://{hostname}/amfa/v1"
    }
  ],
  "x-akamai": {
    "auth-type": "EDGE_GRID",
    "file-path": "02-users.yaml"
  },
  "x-readme": {
    "explorer-enabled": false,
    "samples-languages": [
      "curl",
      "python",
      "node"
    ]
  }
}
```

# Sibling pages

* [List users](https://techdocs.akamai.com/mfa/reference/get-users.md)
* [Get a user](https://techdocs.akamai.com/mfa/reference/get-user.md)
* [Update a user](https://techdocs.akamai.com/mfa/reference/put-user.md)
* [Delete a user](https://techdocs.akamai.com/mfa/reference/delete-user.md)