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

# Create a Machine Authenticator

`POST /api/web/v1/users/{userid}/machines`

Create a Machine Authenticator for a user. Caller requires the USERMACHINES:ADD permission.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| userid | path | Yes | string | The UUID of the user for which the machine authenticator is to be added. |

## Request Body

Required.

### application/json

Schema

```json
{
  "required": [
    "label"
  ],
  "type": "object",
  "properties": {
    "fingerprint": {
      "type": "string",
      "description": "The device fingerprint. It must be a valid fingerprint as produced by Entrust SDK.",
      "example": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}"
    },
    "label": {
      "type": "string",
      "description": "Identifies the device/machine from the end-user point of view.",
      "example": "MachineAuthenticatorLabel"
    }
  },
  "description": "Register a machine authenticator for authentication to Identity as a Service",
  "title": "MachineAuthenticatorRegistration"
}
```

## Responses

### 200

Successful

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "machineAuthenticator": {
      "type": "object",
      "properties": {
        "fingerprint": {
          "type": "string",
          "description": "The device fingerprint if it's required during Machine authentication. It will always be null when returned from IDaaS as part of the response body.",
          "example": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}"
        },
        "machineNonce": {
          "type": "string",
          "description": "machineNonce",
          "example": "07ZeToA3YfoATTxoU6h2x=="
        },
        "sequenceNonce": {
          "type": "string",
          "description": "sequenceNonce",
          "example": "03ReToA37851tyVU8f3y=="
        }
      },
      "description": "Machine authenticator required to complete authentication challenge",
      "title": "MachineAuthenticator"
    },
    "userMachineAuthenticator": {
      "required": [
        "id",
        "label",
        "registrationTime"
      ],
      "type": "object",
      "properties": {
        "expiryTime": {
          "type": "string",
          "description": "When this machine secret expires in UTC time",
          "format": "date-time",
          "example": "2019-02-19T13:15:27Z"
        },
        "id": {
          "type": "string",
          "description": "Identifies the device/machine"
        },
        "label": {
          "type": "string",
          "description": "Identifies the device/machine from the end-user point of view"
        },
        "lastUsedTime": {
          "type": "string",
          "description": "When this machine secret was last used",
          "format": "date-time",
          "example": "2019-02-19T13:15:27Z"
        },
        "registrationTime": {
          "type": "string",
          "description": "When this machine secret was created in UTC time",
          "format": "date-time",
          "example": "2019-02-19T13:15:27Z"
        }
      },
      "description": "UserMachineAuthenticator",
      "title": "UserMachineAuthenticator"
    }
  },
  "title": "MachineAuthenticatorRegistrationResult"
}
```

### 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": [
      "USERMACHINES:ADD"
    ]
  }
]
```