Nextcloud

Let hires find and read files in your own Nextcloud, and upload, share or delete only as you allow.

Explore 6 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Nextcloud, a hire can:

list what's in a folder,
find files by name,
read a file as text: text files (txt, md, csv, json, code…), and Word, Excel, PowerPoint and OpenDocument files, which Roster turns into text itself. Of a large text file it reads the start. Other files (PDFs, images) show their name, size and date only, never their content.

If you allow changes, a hire can also:

upload text as a file. It never overwrites a file: replacing one asks a person first.
make a public link to a file, read only, ending after 1 to 90 days (7 unless it says otherwise). Anyone with the link can open the file, so this always asks a person first.
delete a file. This always asks a person first. With Nextcloud's trash bin on, it can be restored from there.

Hires never see the password. Passwords and keys written inside files are hidden from hires when they read them.

1. Make an app password

Straight there: https://<your-nextcloud>/index.php/settings/user/security. Once you've typed your Nextcloud's address in Roster, the form links to it.

In Nextcloud, make a user for Roster (or use an existing one), and share with it only the folders hires should see.
Signed in as that user: Personal settings → Security → Devices & sessions. Type a name like "Roster" and click Create new app password.
Copy the username and the app password.

2. Connect it in Roster

Open Integrations → Tools → Add a tool, search for Nextcloud and choose it.
Nextcloud address: like https://cloud.example.com.
Paste the Username and App password.
What hires may do: Find and read files, or also upload, share and delete.

Roster checks the key when you click Connect. Once it's accepted, the connection shows Connected as the Nextcloud user's name and the address. If it's refused, Roster says what to fix (a mistyped key, a missing permission) and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on Nextcloud. Read only gives the reading tools; Read and write adds upload, links and delete (if the connection allows changes).

Folders: paths like /Clients, from the top of that user's files. Files in their subfolders count. Leave it empty for everything the user can see.

When it asks first

What the hire does	Asks a person
Makes a public link	always
Deletes a file	always
Uploads a file with a taken name	only when it asks to replace the old file

You can change this per hire on the hire's Tools tab, under When it asks first.

If something goes wrong

"Didn't accept the connection's credential": the app password was revoked, or the username is wrong. Make a new app password.
Search finds nothing: search looks at file names, not what's inside files.
Links can't be made: public links may be turned off in Nextcloud's sharing settings, or need a password there.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Nextcloud and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

User name and password or key pair

In Nextcloud: Personal settings → Security → Create new app password. Use a user made for Roster, with only the folders hires should see shared with it.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Nextcloud connection fields
Field	What to provide
Username `username` Optional	In Nextcloud: Personal settings → Security → Create new app password. Use a user made for Roster, with only the folders hires should see shared with it.
App password `appPassword` Optional · sealed secret	Use the value for your account or connection.
Nextcloud address `url` Required	Use the value for your account or connection.
What hires may do `access` Optional	Read only asks Nextcloud for less, and hires get no tool that changes anything. Changing this may mean signing in again. Choices: Find and read files (read); Also upload, share (asks first) and delete (asks first) (write). Starts with: `read`.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Nextcloud per-hire limits
Field	What to provide
Folders `folders` Optional	Folders the hire may use, as paths like /Clients. Files in their subfolders count. Leave empty for everything the connection can see.

Actions

6 actions: 3 only read and 3 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

Find an actionAccess

6 of 6 actions. Open an action for its arguments and full input schema.

search_filesRead only

Find files in Nextcloud by words in their name, optionally inside one folder.

Approval: Uses your workspace and hire approval settings.

Arguments for search_files
Argument	Type	Details
`text`Required	string	words to look for
`folder`Optional	string	a folder's path, like /Clients
`limit`Optional	integer	See input schema below.Default: `20`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "words to look for"
    },
    "folder": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "a folder's path, like /Clients"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "text"
  ]
}

list_folderRead only

What's directly inside a Nextcloud folder: files and subfolders, newest first where Nextcloud sorts.

Approval: Uses your workspace and hire approval settings.

Arguments for list_folder
Argument	Type	Details
`folder`Optional	string	a folder (path); leave out for the top
`limit`Optional	integer	See input schema below.Default: `50`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "description": "a folder (path); leave out for the top",
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    },
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}

read_fileRead only

Read a Nextcloud file as text: text files (the start of large ones), Word, Excel, PowerPoint and OpenDocument files. Other files (PDFs, images) show their details only.

Approval: Uses your workspace and hire approval settings.

Arguments for read_file
Argument	Type	Details
`file`Required	string	the file's path, like /Clients/notes.md (from list_folder or search_files)

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "the file's path, like /Clients/notes.md (from list_folder or search_files)"
    }
  },
  "required": [
    "file"
  ]
}

upload_fileRead and write

Save text as a file in a Nextcloud folder (a note, a CSV, a Markdown report). It never overwrites: if the name is taken it says so, and replace: true replaces the file after a person approves.

Approval: when it would replace a file that's already there.

Available with: What hires may do: Also upload, share (asks first) and delete (asks first).

Arguments for upload_file
Argument	Type	Details
`folder`Required	string	a folder's path, like /Clients
`name`Required	string	the file's name with its extension, like summary.md or rates.csv
`text`Required	string	the file's whole content, as text
`replace`Optional	boolean	replace a file of the same name (asks a person first)Default: `false`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "a folder's path, like /Clients"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the file's name with its extension, like summary.md or rates.csv"
    },
    "text": {
      "type": "string",
      "maxLength": 1000000,
      "description": "the file's whole content, as text"
    },
    "replace": {
      "default": false,
      "description": "replace a file of the same name (asks a person first)",
      "type": "boolean"
    }
  },
  "required": [
    "folder",
    "name",
    "text"
  ]
}

share_linkRead and write

Make a link to a Nextcloud file that anyone who has it can open, lasting up to 90 days. It waits for a person's approval: Roster asks in the thread and makes the link, once, when they approve.

Approval: Always asks for approval.

Available with: What hires may do: Also upload, share (asks first) and delete (asks first).

Arguments for share_link
Argument	Type	Details
`file`Required	string	the file's path, like /Clients/notes.md (from list_folder or search_files)
`audience`Optional	"anyone"	anyone with the link, or only people signed in to the organisationDefault: `"anyone"`
`expires_in_days`Optional	integer	when the link stops workingDefault: `7`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "the file's path, like /Clients/notes.md (from list_folder or search_files)"
    },
    "audience": {
      "default": "anyone",
      "description": "anyone with the link, or only people signed in to the organisation",
      "type": "string",
      "enum": [
        "anyone"
      ]
    },
    "expires_in_days": {
      "default": 7,
      "description": "when the link stops working",
      "type": "integer",
      "minimum": 1,
      "maximum": 90
    }
  },
  "required": [
    "file"
  ]
}

delete_fileRead and write

Delete a Nextcloud file (to Nextcloud's trash bin, if it's on). It waits for a person's approval: Roster asks in the thread and deletes it, once, when they approve. Folders aren't deleted here.

Approval: Always asks for approval.

Available with: What hires may do: Also upload, share (asks first) and delete (asks first).

Arguments for delete_file
Argument	Type	Details
`file`Required	string	the file's path, like /Clients/notes.md (from list_folder or search_files)

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "the file's path, like /Clients/notes.md (from list_folder or search_files)"
    }
  },
  "required": [
    "file"
  ]
}

Watches and incoming events

No built-in watch is declared. Give a hire a scheduled responsibility if it should check this service regularly.
No incoming webhook handler is declared for this integration.

Limits and troubleshooting

Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
Expired or revoked access: reconnect or replace the key on the connection.
Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

1. Make an app passwordCopy Anchor Link

2. Connect it in RosterCopy Anchor Link

3. Give hires accessCopy Anchor Link

When it asks firstCopy Anchor Link

If something goes wrongCopy Anchor Link

Tools and permissions reference

Authentication and requested permissions

User name and password or key pair

Connection fields

Per-hire limits

Actions

Watches and incoming events

Limits and troubleshooting

On this page

1. Make an app password

2. Connect it in Roster

3. Give hires access

When it asks first

If something goes wrong