> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting Flat Files with Lumos

Ingest user and access data into Lumos from CSV files, for systems with no API or database access, or where existing processes already produce file exports. Lumos reads the file from an S3 bucket or SFTP server on a schedule, and you map its columns to Lumos fields.

## File structure

Lumos expects certain standard fields from any flat file:

* **Unique ID**: a unique identifier for each account
* **First Name and Last Name**: full name
* **Email**: corporate email address
* **Status**: account status, using exactly these values: `ACTIVE`, `INACTIVE`, `SUSPENDED`, `DEPROVISIONED`, `PENDING`, `DELETED`

The only strictly required fields are email OR full name (first name AND last name). Additional columns become custom attributes and permissions as you map them. A full template with filled example rows is on [Flat File CSV Example](/integrations/generics/flatfile/examples).

> **Encoding**
>
> The connector works best with UTF-8 encoded files. Converting from Excel: **File > Save As**, then choose **CSV UTF-8 (Comma Delimited)** in the Save as type dropdown.

**Sync cadence.** Lumos pulls from flat file connections through platform-wide scheduled syncs, daily by default.

**Multiple entitlements per account.** Files that list each account-entitlement pair on its own row are supported, so one account may span multiple rows. Lumos determines each account's Last Login and Last Activity by taking the most recent timestamps across all of that account's rows.

## Connecting via S3

You can reuse one S3 bucket for multiple applications. Repeat the connection per application with a unique file name and mapping for each. Three authentication options:

### Access Key ID

The IAM user that owns these keys needs read access to the file. The read policy shown under IAM Role below (`s3:ListBucket` on the bucket and `s3:GetObject` on its contents) works for keys too.

1. Click the Flatfile connector tile on the integrations tab.
2. Enter the **Access Key ID** and **Secret Access Key** for the AWS account containing the bucket, the **S3 Bucket Name**, and the **S3 File Name**.
3. Click **Connect**.

### IAM Role

1. Click the Flatfile connector tile and note the Lumos-generated **external ID** in the instructions.
2. In AWS, go to **IAM > Roles > Create Role** and select **Custom Trust Policy**. Use this policy, replacing `<lumos-external-id>`:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Statement1",
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::349123981986:user/global-service-account" },
      "Action": "sts:AssumeRole",
      "Condition": { "StringEquals": { "sts:ExternalId": "<lumos-external-id>" } }
    }
  ]
}
```

3. Skip **Add permissions**, name the role, and create it.
4. Open the role, go to **Permissions > Add permissions > Create inline policy**, and grant read access to the bucket, replacing `<bucket-name>`:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::<bucket-name>" },
    { "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::<bucket-name>/*" }
  ]
}
```

5. Copy the role ARN, and in the Lumos instructions enter the **AWS IAM Role ARN**, the **S3 Bucket Name**, and the **S3 File Name**, then click **Connect**.

### Private access (On-Prem only)

Running the On-Prem Flatfile connector as a Docker deployment on ECS, you can grant the container direct bucket access. Configure the ECS task with a policy allowing `s3:GetObject`, `s3:GetObjectVersion`, `s3:GetBucketLocation`, `s3:ListBucket`, and `s3:HeadBucket` on your bucket. Then select the **Flatfile Connector (On Prem)** option on the integrations page, choose `AWS_S3_PRIVATE_ACCESS` as the source type, enter the bucket and file name, and click **Connect**.

## Connecting via SFTP

As with S3, reuse one server across applications by reconnecting with a unique file path and mapping per application.

### Username and password

1. Click the Flatfile connector tile.
2. Enter the **Username**, **Password**, **Hostname**, and the full **File path** on the server.
3. Click **Connect**.

### Key pair

1. Click the Flatfile connector tile.
2. Enter a unique key identifier and click **Get key**.
3. Copy the generated public key and add it to your SFTP server's known keys.
4. Enter the **Username**, **Hostname**, and full **File path**, then click **Connect**.

## Configuring the CSV mapping

Before mapping, validate that each account has a unique identifier and that status values use the expected enumerations.

1. Go to the application created from the flat file connection.
2. Click **Configure Mappings** on the app page.
3. Map each CSV column to its Lumos field.
4. Click **Preview Table** to check the result.
5. Select **Finish Import**.