Skip to content

API Keys — create & use

ImmPort APIs now accept scoped API keys created via the Auth Service UI. The legacy username/password token exchange is deprecated for general automation; create keys in the Auth UI and use them as a Bearer token in requests.

Create a key

  1. Open: https://www.dev.immport.org/auth/api/keys
  2. Click "Create key". Optionally provide a human-friendly label (e.g. "ci-runner" or "alice-laptop") to help manage keys in the UI.
  3. Select one or more scopes required for your usage: browse, download, upload.
  4. The UI will return a JSON object containing an "api_key" value — copy it now. The key cannot be retrieved later from the UI.

Example API key JSON (returned by the UI):

{
  "id": "8c3e4394-10a9-46ef-8af9-b6401ba1400d",
  "api_key": "eyJraWQiOiJDbHVV8mUaJKrMDS1mq0NoiMX51yPeUnTp3yLQqZco7iwFYdlCpcZ_0hCGt1NJ974uI7c9uQ",
  "expires_at": "2026-05-21T20:55:24.654328038Z"
}

Using your API key

Include the api_key value from the JSON in the Authorization header as a Bearer token.

Example (curl):

curl -H "Authorization: Bearer <API_KEY>" "https://api.immport.org/shared/data?studyAccession=SDY1"

Recommended environment variable pattern for scripts:

export IMMPORT_API_KEY="<your_api_key_here>"
curl -H "Authorization: Bearer ${IMMPORT_API_KEY}" "https://api.immport.org/shared/data?studyAccession=SDY1"

Scopes

  • browse — read-only access to study metadata and public/shared resources.
  • download — permission to download shared data files (shared data).
  • upload — create and manage private data in your workspace and submit uploads (requires workspace/study access).

Using API keys with Swagger UI

Open the Shared Data Swagger page and click the "Authorize" button. Paste the API key value into the Bearer token field. If the Swagger UI requires the full Bearer prefix, enter Bearer <API_KEY>; otherwise paste just the token.

Security notes

  • Treat API keys like secrets. Store them in secure credential stores or environment variables.
  • Rotate keys periodically and remove keys that are no longer used.