# Username (ID)

## Definition and Default Configuration

The **username (ID)** is considered a factor as well, though it will mostly serve for identifying a user as a first-step in order to continue the authentication with other non-unique factors (such as OTP or password for example).

To the Quasr platform, the **username** value has no semantic meaning; whether the end-user uses their email address, their real-name or a fictitious nickname makes no difference to Quasr.\
Quasr does not require the **username** value to be any sort of *PII (Personal Identifiable Information)*.

The default allowed **username** value pattern is very flexible, allowing any character and a **length** between **1-100 characters**. There is also no limitation on the **character set** - if a user prefers to use Chinese or Cyrllic characters, they can do so. 

The default **maximum failed attempts** before the factor gets temporarily disabled is **5**. The factor will auto-unlock after 300 seconds (5 minutes). The counter resets to 0 on each successful login.

**Usernames** are **non-case-sensitive** by default.

**Usernames** values are stored **hashed**, using the Argon2id algorithm.

## User Interface (UI) Example

Below is a sample screenshot to give an idea of a potential login / registration page asking for a **username**. On a login or registration page, the username input field is usually represented by a single-line text field.

<figure><img src="/files/RPTPwjdm0q6S725Y6DzQ" alt="" width="366"><figcaption><p>Example of username login on the Hosted Login UI (Quasr)</p></figcaption></figure>

## Signup with a username

{% hint style="info" %}
This step is done by the end-users, usually at initial signup to a web service or to add an additional authentication method (factor) to their existing one as additional option.
{% endhint %}

To signup with a **username**, the actual **username value** (`input` parameter) and optionally a **label** (`label` parameter) is provided.

## Enrolling a username factor

<mark style="color:green;">`POST`</mark> `https://{tenant_id}.api.quasr.io/factors/signup`

#### Request Body

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| input                                | String | ID value    |
| label                                | String | Label       |
| id<mark style="color:red;">\*</mark> | String | Factor ID   |

{% tabs %}
{% tab title="200: OK Failed enrollment" %}

```javascript
{
  "result": "FAILED",
  "feedback": {
    "cause": "INVALID_INPUT"
  }
}
```

{% endtab %}

{% tab title="200: OK Successful enrollment (with access token)" %}

```javascript
{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrollment_id": "<enrollment id>",
    "generated_input": "<generated_input>" // in case input was not provided
  }
}
```

{% endtab %}

{% tab title="200: OK Successful enrollment (with session token)" %}

```javascript
{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrollment_id": "<enrollment id>",
    "generated_input": "<generated_input>" // in case input was not provided
  },
  "session_token": "<session_token>",
  "account_id": "<account_id>",
  "session_score": <session_score>,
  "session_exp": <session_expiration> // epoch in seconds (not ms)
}
```

{% endtab %}
{% endtabs %}

## Login with a username

{% hint style="info" %}
This step is done by the end-users, in order to authenticate themselves (login).
{% endhint %}

To validate a **username** factor, the actual **username value** (`input` parameter) is provided.

## Validating a username factor

<mark style="color:green;">`POST`</mark> `https://{tenant_id}.api.quasr.io/factors/login`

#### Request Body

| Name                                    | Type   | Description             |
| --------------------------------------- | ------ | ----------------------- |
| input<mark style="color:red;">\*</mark> | String | ID value                |
| id<mark style="color:red;">\*</mark>    | String | Factor or Enrollment ID |

{% tabs %}
{% tab title="200: OK Successful validation (with session token)" %}

```json
{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrolment_id": "<enrollment_id>"
  },
  "session_token": "<session_token>",
  "account_id": "<account_id>",
  "session_score": <session_score>,
  "session_exp": <session_expiration> // epoch in seconds (not ms)
}
```

{% endtab %}

{% tab title="200: OK Failed validation" %}

```javascript
{
  "result": "FAILED",
  "feedback": {
    "cause": "ENROLLMENT_NOT_FOUND",
  }
}
```

{% endtab %}
{% endtabs %}

## **Factor Creation via Management API**

{% hint style="info" %}
This step is done by the Quasr customer's Tenant Administrator, to provide this factor as an authentication option to their end-users.
{% endhint %}

A **username factor** is already available for all newly created tenants by default, however, if you want to add additional ID factors, you can do so via [Tenant Administration UI](broken://pages/xT9DB1eLOv3hNxZlVxGT) or [Admin API](/quasr/tenant-administration/apis/management-api-graphql.md).

The following API sample calls create a **username factor** labelled *"Another Username"* with a score of *1*.

The **username factor** allows for the following **parameters** and **config options**:

<table><thead><tr><th width="213">Parameter</th><th width="233">Value Options</th><th width="185">Default Value</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>subtype</strong></mark></td><td>"secret:id"</td><td></td><td>true</td></tr><tr><td><mark style="color:blue;"><strong>label</strong></mark></td><td><em>&#x3C;any string></em></td><td>"Username"</td><td>false</td></tr><tr><td><mark style="color:blue;"><strong>status</strong></mark></td><td> "ENABLED" | "DISABLED"</td><td>"DISABLED"</td><td>false</td></tr><tr><td><mark style="color:blue;"><strong>score</strong></mark></td><td><em>&#x3C;positive int></em></td><td>1</td><td>false</td></tr><tr><td><mark style="color:blue;">config.</mark><br><mark style="color:blue;"><strong>regex</strong></mark></td><td>regex</td><td>"^.{1,100}$"</td><td>false</td></tr><tr><td><mark style="color:blue;">config.<strong>unique</strong></mark></td><td>true | false</td><td>true</td><td>false</td></tr><tr><td><mark style="color:blue;">config.</mark><br><mark style="color:blue;"><strong>case_sensitive</strong></mark></td><td>true | false</td><td>false</td><td>false</td></tr><tr><td><mark style="color:blue;">config.</mark><br><mark style="color:blue;"><strong>public_signup</strong></mark></td><td>true | false</td><td>false</td><td>false</td></tr><tr><td><mark style="color:blue;">config.<strong>threshold</strong></mark></td><td>0-4</td><td>0</td><td>false</td></tr><tr><td><mark style="color:blue;">config.<strong>require_validation_for_enablement</strong></mark></td><td>true | false</td><td>false</td><td>false</td></tr><tr><td><mark style="color:blue;">config.<strong>capture_input</strong></mark></td><td>true | false</td><td>false</td><td>false</td></tr></tbody></table>

{% hint style="info" %}
The Quasr Access Token used in the `Authorization` header in the examples below must contain the scope `https://api.quasr.io/scopes/admin` in order to be authorized. See [API Authorization](/quasr/tenant-administration/apis/management-api-graphql.md#api-authorization)
{% endhint %}

### GraphQL Example

```graphql
// GraphQL Query (Sample)
mutation createFactor ($input: CreateFactorInput!) {
    createFactor (input: $input) {
        id
    }
}

// GraphQL Variables (Sample)
{
  "input": {
    "subtype": "secret:id",
    "regex": "^.{1,100}$",
    "label": "My Username",
    "status": "ENABLED",
    "score": 1
  }
}

// Response (Sample)
{
    "data": {
        "createFactor": {
            "id": "678c0054-d57e-4e09-9e54-ef8deb4ddd72"
        }
    }
}
```

### Node.js Example

```javascript
var axios = require('axios');
var data = JSON.stringify({
  query: `mutation createFactor ($input: CreateFactorInput!) {
    createFactor (input: $input) {
        id
    }
}`,
  variables: {
    "input": {
      "subtype": "secret:id",
      "regex": "^.{1,100}$",
      "label": "Another ID",
      "status": "ENABLED",
      "score": 1
    }
  }
});

var config = {
  method: 'post',
  url: 'https://{tenant_id}.api.quasr.io/graphql',
  headers: { 
    'Authorization': 'Bearer {access_token}', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.quasr.io/quasr/tenant-administration/factors/username-id.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.