Skip to content

Puhti and Mahti computing services have been decommissioned. Puhti and Mahti login nodes and storage services will remain available until 15 October 2026, but are no longer covered by service contracts. Please clean up and migrate your data to Roihu ASAP. See Roihu data migration guide for instructions.

Connecting to FirecREST HPC API

Access tokens are secrets

Access tokens issued for FirecREST HPC API allow the token holder to interact with Slurm jobs, and read, manipulate and transfer data with your privileges. Don't share your access token with anyone.

If you suspect that your personal access token might have been compromised, the token should be revoked as soon as possible.

FirecREST HPC API endpoints can be found under the following URLs:

The HPC API service uses versioned URL scheme, where the first element of the URL path represents the API generation. The current, latest API generation is v1. It is based on the latest release of FirecREST v2.

Possible major or breaking changes to the API will be released as new API generation. By default, a new release will not replace any existing APIs. Earlier generations will be maintained and kept available.

Subsystems

FirecREST HPC API supports multiple subsystems with different configuration options, identified by subsystem identifier in API endpoint URLs (e.g. /v1/compute/<subsystem>/jobs).

LUMI API configuration details

API and subsystem configuration on api.lumi.csc.fi:

API generation API subsystem Partitions Data transfer
v1 lumi LUMI-C, LUMI-G, LUMI-D S3 via LUMI-O, pre-signed URLs

Roihu API configuration details

API and subsystem configuration on api.roihu.csc.fi:

API generation API subsystem Partitions Data transfer
v1 cpu All CPU partitions S3 via Allas, pre-signed URLs
v1 gpu All GPU partitions S3 via Allas, pre-signed URLs

API documentation

Up-to-date API specification for v1 is available in OpenAPI format via /v1/openapi.json endpoint on all FirecREST API instances (for example, https://api.roihu.csc.fi/v1/openapi.json). The API documentation can be viewed through FirecREST's Swagger UI at /v1/docs/ (for example, https://api.roihu.csc.fi/v1/docs/).

Connecting to the API

FirecREST HPC API uses JWT bearer tokens as authorization method. Accepted tokens are issued by CSC authentication and authorization infrastructure (AAI) identity provider (IdP). Only those tokens that have been specifically issued to be used with FirecREST HPC API (indicated by aud member in the JWT) are accepted by the API.

In order to connect to an API endpoint, tokens are sent to FirecREST using standard Authorization header, example:

access_token="<JWT>"
curl -X GET https://api.roihu.csc.fi/v1/compute/cpu/jobs \
  -H "Authorization: Bearer ${access_token}"

Authorization header must be present in every API request sent to FirecREST. Token validity is verified on server-side for each request. An attempt to use invalid access token will result in a HTTP 401 Unauthorized return code, with a specific error message recorded in a JSON document in the response body.

All requests sent to the API are executed on the target system using the same user account that was used to retrieve the access token. For example, with a personal access token, all commands run via FirecREST are executed under your own user account and privileges.

Connecting with a personal access token

FirecREST HPC API can be used with personal access tokens, which allow access to same computing resources and projects as your direct terminal access. Personal access tokens are useful for running desktop applications or automation utilities in interactive terminals, that integrate with HPC resources using PyFirecREST Python SDK, for example.

As the name suggests, personal access tokens are intended for personal use. A project-specific robot account should be used for implementing machine-to-machine HPC API integration for headless non-interactive systems.

A personal access token can be retrieved from the MyCSC FirecREST token service. Note that there's no direct link to the token service from the MyCSC portal itself yet. Personal access tokens are valid for 24 hours at a time.

Revoking a personal access token

In an event where a personal access token is suspected to have been compromised (was accidentally committed to a public source repository or pasted in a chat or email, for example), you should revoke the potentially compromised token and generate a new one.

You can view and revoke your active tokens at CSC IdP federated personal profile page, under Connected organizations -> Firecrest-access-tokens. All valid, revocable tokens will show a red Revoke now button when the Firecrest-access-tokens view is expanded.

Connecting with a robot account

Machine-to-machine robot accounts can access computing resources on Roihu using FirecREST HPC API.

Similarly to personal access tokens, connecting to the API using a robot account also requires supplying a JWT bearer token as authorization credential. Robot accounts can request a suitable JWT from the token endpoint on CSC IdP using standard OAuth 2.0 Client Credentials Grant.

Settings typically required for client credentials configuration:

Setting Value
Client ID Username of your robot account
Client Secret Password of your robot account
Token URL https://user-auth.csc.fi/idp/profile/oidc/token
Scope openid

You can, for example, retrieve an access token for a robot account with a simple curl call:

curl -X POST https://user-auth.csc.fi/idp/profile/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "client_id=${my_robot_username}&client_secret=${my_robot_password}&scope=openid&grant_type=client_credentials"

A successful call returns a JSON document with the access token and associated metadata (token type, scope and lifetime).