Account and Workspace
Before you can upload anything you need two things: an ImmPort account and access to a workspace.
1. Create an ImmPort account
Register at https://www.dev.immport.org/auth/login if you don't already have an account. Every upload, whether through the website or the API, is tied to your account.
2. Get a workspace
A workspace is a private, access-controlled area where your uploads live. It can contain several studies and several users. Data stays visible only to workspace members until a study is released, and it stays in the workspace after release.
| Your situation | What to do |
|---|---|
| Your team has no workspace yet | Submit the Workspace Request Form |
| Your team already has a workspace | Ask a workspace Administrator to add you |
| You're adding another study | Reuse your existing workspace, especially if the new study shares subjects with an earlier one (why) |
When you request a new workspace, choose your own role:
- Administrator: you can add other users and assign roles, and you can register studies once the request is approved.
- Submitter: you must give the email address of at least one Administrator. You can register studies but can't add users.
Workspace roles
Every workspace member has one of three roles. Each workspace needs at least one Administrator and can have up to three. There's no limit on Submitters or Viewers.
| What the user can do | Administrator | Submitter | Viewer |
|---|---|---|---|
| Register new studies | ✅ | ✅ | — |
| Edit studies they registered | ✅ | ✅ | — |
| Edit other studies in the workspace | ✅ all | if granted | — |
| View study metadata and download files | ✅ all | studies they can access | if granted |
| See other workspace users | ✅ | if granted | if granted |
| Add or remove users, assign roles | ✅ | — | — |
| Grant per-study read/write access | ✅ | — | — |
Administrator: the workspace's main contact, often a PI, lab manager or lead data submitter. You become an Administrator by choosing that role when you request the workspace, or when another Administrator gives you the role. Administrators invite users by email address.
Submitter: someone who manages and uploads data. Registering a study automatically gives you read/write access to it. You can edit other studies only when an Administrator grants access.
Viewer: someone who reviews studies but doesn't edit them. Viewers have read-only access to the studies an Administrator shares with them.
These roles control access inside ImmPort's private workspaces only. They have no meaning outside ImmPort.
Uploading through the API
Uploads run with the permissions of the account behind the API key. A Viewer can't upload or validate, so those calls are rejected however correct the request is. Use an account that is a Submitter or Administrator on the workspace and has write access to the study. If an upload is rejected for permissions, ask an Administrator to change the account's access. Retrying won't help.