Slurm REST API and Tokens

Slurm offers a REST API (slurmrestd) that lets scripts and tools query jobs and the cluster over HTTP instead of running squeue, sacct or sbatch. Each request is authenticated with a personal API token that you create yourself.

info

The API and its addresses are reachable only from inside the supercomputer, for example from a login node or from within a job.

Create a token

Run scontrol token on the cluster you want to use. It prints a line that sets the SLURM_JWT environment variable:

$ scontrol token lifespan=86400
SLURM_JWT=eyJhbGciOiJIUzI1NiIs...

To put the token straight into your environment:

export $(scontrol token lifespan=86400)

• lifespan is in seconds. Without it, a token lasts 30 minutes.
• The longest lifespan allowed is 30 days (lifespan=2592000). Longer requests are refused.
• A token belongs to the cluster that issued it. A Sol token does not work on Phoenix, and the reverse.

Use the API

Send your username and token as HTTP headers. The current API version is v0.0.45.

Cluster	Base address
Sol	http://sol-slurmrestd.sol.rc.asu.edu:6820
Phoenix	http://phx-slurmrestd.phx.rc.asu.edu:6820

Sol

export $(scontrol token lifespan=3600)
curl -s \
-H "X-SLURM-USER-NAME: $USER" \
-H "X-SLURM-USER-TOKEN: $SLURM_JWT" \
http://sol-slurmrestd.sol.rc.asu.edu:6820/slurm/v0.0.45/jobs/

Phoenix

export $(scontrol token lifespan=3600)
curl -s \
-H "X-SLURM-USER-NAME: $USER" \
-H "X-SLURM-USER-TOKEN: $SLURM_JWT" \
http://phx-slurmrestd.phx.rc.asu.edu:6820/slurm/v0.0.45/jobs/

The full list of endpoints, including job submission, is available from the server itself at /openapi/v3 (send the same headers). SchedMD documents it in the Slurm REST API reference.

Keep your token safe

A token works as you: anyone who has it can see and submit jobs in your name until it expires.

• Treat it like a password. Do not paste it into chats or tickets, commit it to Git, or put it in files other people can read.
• Use the shortest lifespan that works. An hour or a day is enough for most scripts; create a fresh token each time a script runs rather than storing a long-lived one.
• A single token cannot be revoked. If you think a token has leaked, contact Research Computing right away.