Authentication and Authorization¶

Authentication determines who is making the request. Authorization then determines what that request is allowed to do.

NOMAD supports multiple authentication mechanisms for API requests using different types of tokens.

The following diagram summarizes how access to an API endpoint is evaluated. Administrator-configurable settings are highlighted in red.

%%{init:{
  'themeVariables': {
    'fontSize': '36px'
  }
}}%%
flowchart TD
    A[Request reaches Oasis] --> B{Network access allowed by deployment?}
    B -- No --> X[Access blocked outside NOMAD]
    B -- Yes --> C{Valid token provided?}

    C -- No --> D{`auth.require_authentication`}
    D -- true --> Y[HTTP 401 Unauthorized]
    D -- false --> E[use `unauthenticated_user_scopes`]

    C -- Yes --> F[Resolve user and token scopes]
    F --> G{User exists and is valid?}
    G -- No --> Z[HTTP 403 Forbidden]
    G -- Yes --> H{`authorized_users` configured<br/>and user not in list?}

    H -- No --> I[Use token scopes]
    H -- Yes --> J{`reject_unauthorized_users`}
    J -- true --> K[HTTP 403 Forbidden]
    J -- false --> L[use `unauthorized_user_scopes`]

    E --> M{Required endpoint scopes present?}
    I --> M
    L --> M

    M -- Yes --> N[Request allowed]
    M -- No --> O[HTTP 403 Forbidden<br/>Missing scopes]

    class D,E,H,J,L config
    class N success

    classDef config stroke:#d73a49,stroke-width:4px;
    classDef success stroke:#2ea44f,stroke-width:4px;

Access tokens¶

NOMAD supports several types of access tokens for authenticating and authorizing API requests:

Keycloak access tokens – obtained through the login flow used by the web UI or API clients
Personal Access Tokens (PATs) – long-lived tokens created by users for scripts and automation
Upload tokens (legacy, deprecated — will be removed in a future release)
Simple (app/signature) tokens (legacy, deprecated — will be removed in a future release)

Keycloak access tokens¶

Keycloak access tokens authenticate a user through the NOMAD identity provider keycloak using OpenID Connect (OIDC).

Short-lived (currently 24 hours) and may require refreshing
Primarily intended for interactive use (e.g. via the GUI)
Grant the full set of user scopes (no scope restriction possible)

Due to these limitations, they are generally not suitable for long-running scripts or automated workflows. Use Personal Access Tokens (PATs) instead.

Personal Access Tokens (PATs)¶

Personal Access Tokens (PATs) are tokens created by users for programmatic access, such as scripts, or automated workflows.

PATs can be issued with explicit scopes, allowing fine-grained control over the operations a user or token is allowed to perform.

Unlike Keycloak access tokens, which typically have fixed and short lifetimes, PATs can be created with a customizable expiration time, making them well suited for long-running scripts or integrations where repeatedly acquiring new tokens would be inconvenient.

PAT scopes must always be explicitly specified. Wildcard expressions such as *:read are supported only in configuration and are not allowed in tokens.

For programmatic API usage, Personal Access Tokens are generally the recommended authentication method.

Deprecated tokens

Upload tokens¶

Upload tokens are legacy tokens with a fixed scope set. They only grant upload-related permissions: uploads:*.

Simple tokens¶

Simple tokens are legacy tokens that grant a broad set of user permissions, effectively corresponding to full access except for token-management scopes.

Both token types are deprecated and will be removed in a future release. They should not be used for new integrations. Use Personal Access Tokens (PATs) instead.

Authorization via scopes¶

Authorization to use specific API features is scope-based. After authentication, NOMAD determines the effective scopes that apply to the request. Scopes define which API operations a user or token is allowed to perform.

A scope defines a permission in the format:

<resource>:<action>

Examples:

uploads:read
uploads:write

When an API endpoint is called, NOMAD checks whether the request has the scopes required by that endpoint. If the required scopes are missing, the request is rejected.

For example, if an endpoint requires uploads:write and the token only has uploads:read, the request will be rejected.

The following table lists all available authorization scopes.

In Python code, scopes are defined as enum members (e.g. Scope.DATASETS_READ), whose value corresponds to the string representation used in tokens and configuration (e.g. datasets:read).

Name	Value
`ACTIONS_READ`	`actions:read`
`ACTIONS_RUN`	`actions:run`
`APPS_READ`	`apps:read`
`DATASETS_ASSIGN_DOI`	`datasets:assign_doi`
`DATASETS_DELETE`	`datasets:delete`
`DATASETS_READ`	`datasets:read`
`DATASETS_WRITE`	`datasets:write`
`ENTRIES_READ`	`entries:read`
`ENTRIES_WRITE`	`entries:write`
`EXTERNAL_DCAT_READ`	`external_dcat:read`
`EXTERNAL_H5GROVE_READ`	`external_h5grove:read`
`EXTERNAL_OPTIMADE_READ`	`external_optimade:read`
`FEDERATION_WRITE`	`federation:write`
`GRAPH_READ`	`graph:read`
`GROUPS_DELETE`	`groups:delete`
`GROUPS_READ`	`groups:read`
`GROUPS_WRITE`	`groups:write`
`INFO_READ`	`info:read`
`MATERIALS_READ`	`materials:read`
`METAINFO_READ`	`metainfo:read`
`NORTH_READ`	`north:read`
`NORTH_RUN`	`north:run`
`SCHEMAS_READ`	`schemas:read`
`SUGGESTIONS_READ`	`suggestions:read`
`SYSTEMS_READ`	`systems:read`
`TOKENS_CREATE`	`tokens:create`
`TOKENS_DELETE`	`tokens:delete`
`TOKENS_READ`	`tokens:read`
`UPLOADS_ASSIGN_DOI`	`uploads:assign_doi`
`UPLOADS_PROCESS`	`uploads:process`
`UPLOADS_PUBLISH`	`uploads:publish`
`UPLOADS_READ`	`uploads:read`
`UPLOADS_WRITE`	`uploads:write`
`UPLOADS_BUNDLE_READ`	`uploads_bundle:read`
`UPLOADS_BUNDLE_WRITE`	`uploads_bundle:write`
`USERS_INVITE`	`users:invite`
`USERS_READ`	`users:read`