> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Create unassigned grids

`POST /api/web/v1/grids`

Create the specified number of unassigned grids. Caller requires the GRIDS:ADD permission.

## Request Body

Required.

### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "emailParms": {
      "type": "object",
      "properties": {
        "emailAttributeName": {
          "type": "string",
          "description": "The name of the user attribute to use for email delivery. If not provided, the system-defined email attribute will be used.",
          "example": "external-email"
        }
      },
      "description": "The parameters passed to customize email delivery to a user",
      "title": "EmailParms"
    },
    "gridContent": {
      "type": "array",
      "description": "If provided, the given grid contents are used for the new Grid Card.  The grid contents must match the grid settings for grid size, grid cell size and cell alphabet.  The administrator must have the GRIDCONTENTS:ADD permission to set the grid contents. This argument is ignored when creating unassigned grids.",
      "items": {
        "type": "array",
        "description": "If provided, the given grid contents are used for the new Grid Card.  The grid contents must match the grid settings for grid size, grid cell size and cell alphabet.  The administrator must have the GRIDCONTENTS:ADD permission to set the grid contents. This argument is ignored when creating unassigned grids.",
        "items": {
          "type": "string",
          "description": "If provided, the given grid contents are used for the new Grid Card.  The grid contents must match the grid settings for grid size, grid cell size and cell alphabet.  The administrator must have the GRIDCONTENTS:ADD permission to set the grid contents. This argument is ignored when creating unassigned grids."
        }
      }
    },
    "groups": {
      "type": "array",
      "description": "When creating unassigned grids the list of UUIDs of groups to which the grids will belong.  If not specified, the grids will not belong to any groups.",
      "items": {
        "type": "string",
        "description": "When creating unassigned grids the list of UUIDs of groups to which the grids will belong.  If not specified, the grids will not belong to any groups."
      }
    },
    "numberOfGrids": {
      "maximum": 1000,
      "minimum": 1,
      "type": "integer",
      "description": "The number of grids to create when creating unassigned grids.  If not specified, it defaults to 1.",
      "format": "int32",
      "example": 1
    },
    "serialNumber": {
      "minimum": 1,
      "type": "integer",
      "description": "If provided, the given grid serial number is used for the new Grid Card.",
      "format": "int64",
      "example": 1
    },
    "state": {
      "type": "string",
      "description": "The state (ACTIVE, INACTIVE, or PENDING) of the new grid.  If not specified, the state defaults to PENDING. This argument is ignored when creating unassigned grids.",
      "enum": [
        "ACTIVE",
        "INACTIVE",
        "UNASSIGNED",
        "PENDING",
        "CANCELED"
      ]
    }
  },
  "description": "Optional parameters for the grid create operation.",
  "title": "GridCreateParms"
}
```

## Responses

### 200

Successful

#### application/json

Schema

```json
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "allowedActions": {
        "type": "array",
        "description": "A list of what actions are currently allowed for this grid.",
        "items": {
          "type": "string",
          "description": "A list of what actions are currently allowed for this grid.",
          "enum": [
            "CANCEL",
            "DELETE",
            "ENABLE",
            "DISABLE",
            "ASSIGN",
            "UNASSIGN"
          ]
        }
      },
      "assignDate": {
        "type": "string",
        "description": "For unassigned grids which were assigned to the user, the date on which the grid was assigned.",
        "format": "date-time",
        "example": "2019-02-19T13:17:27Z"
      },
      "createDate": {
        "type": "string",
        "description": "The date on which the grid was created.",
        "format": "date-time",
        "example": "2019-02-19T13:15:27Z"
      },
      "expired": {
        "type": "boolean",
        "description": "A flag indicating if this grid is currently expired."
      },
      "expiryDate": {
        "type": "string",
        "description": "If the grid policy defines an expiry date, the date on which this grid will expire. Expired grids cannot be used for authentication.",
        "format": "date-time",
        "example": "2019-08-19T13:15:27Z"
      },
      "gridContents": {
        "type": "array",
        "description": "The grid contents of this grid.  Only administrators with the GRIDCONTENTS:VIEW permission will receive this value.",
        "items": {
          "type": "array",
          "description": "The grid contents of this grid.  Only administrators with the GRIDCONTENTS:VIEW permission will receive this value.",
          "items": {
            "type": "string",
            "description": "The grid contents of this grid.  Only administrators with the GRIDCONTENTS:VIEW permission will receive this value."
          }
        }
      },
      "groups": {
        "type": "array",
        "description": "The UUIDs of groups to which this grid belongs.  This value is only used for unassigned grids. Only groups to which the current administrator has access will be returned.",
        "items": {
          "type": "string",
          "description": "The UUIDs of groups to which this grid belongs.  This value is only used for unassigned grids. Only groups to which the current administrator has access will be returned."
        }
      },
      "id": {
        "type": "string",
        "description": "The unique UUID assigned to the grid when it is created."
      },
      "lastUsedDate": {
        "type": "string",
        "description": "The date on which this grid was last used for authentication. This value will be null if the grid has never been used.",
        "format": "date-time",
        "example": "2019-02-19T13:15:27Z"
      },
      "serialNumber": {
        "type": "integer",
        "description": "The unique numeric serial number assigned to the grid when it is created.",
        "format": "int64"
      },
      "state": {
        "type": "string",
        "description": "The state of this grid.  Only grids in the ACTIVE or PENDING state can be used for authentication.",
        "enum": [
          "ACTIVE",
          "INACTIVE",
          "UNASSIGNED",
          "PENDING",
          "CANCELED"
        ]
      },
      "userId": {
        "type": "string",
        "description": "The UUID of the user who owns this grid.  If the grid is not assigned, this value will be null.",
        "example": "45f5a855-962a-4b5f-b5c5-7ceeae235875"
      },
      "userName": {
        "type": "string",
        "description": "The user Id for this user.  If the grid is not assigned, this value will be null.",
        "example": "john.doe"
      }
    },
    "description": "A Grid defines the information returned about a Grid.",
    "title": "Grid"
  }
}
```

### 400

Bad Request

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 401

Access denied

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 403

Forbidden

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 404

Not Found

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 409

Conflict

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

## Security

Requirements

```json
[
  {
    "AdminAPIAuthentication": [
      "GRIDS:ADD"
    ]
  }
]
```