Tokens

The Tokens API provides endpoints to introspect and revoke your OLCF Project Access Tokens.

Required Permission: Any valid token can perform these actions on itself.

Note

The Python and Go examples on this page use gRPC client packages that are not yet publicly available. ORNL-internal users may request access by contacting the S3M team: olcf-s3m@email.ornl.gov. The REST API (via curl or otherwise) is available to all users.

Revoke a Token

If your token has been exposed, revoke it immediately.

Revoking a token invalidates it permanently. This is an irreversible action.

DELETE /olcf/v1/token/ctls/revoke

curl

curl -X DELETE -H @.env \
    https://s3m.olcf.ornl.gov/olcf/v1/token/ctls/revoke

Python

from s3m_apis_betterproto.tms.v1 import RevokeAuthTokenRequest

client = factory.create_client(TokenControlStub)
await client.revoke_auth_token(RevokeAuthTokenRequest())

Go

import (
    "context"
    tmspb "s3m.olcf.ornl.gov/apis/tms/v1"
)

client := tmspb.NewTokenControlClient(conn)
_, err := client.RevokeAuthToken(context.Background(), &tmspb.RevokeAuthTokenRequest{})

Python (requests)

import os
import requests

S3M_BASE_PATH = "https://s3m.olcf.ornl.gov/olcf/v1/token/ctls"
S3M_TOKEN = os.getenv("S3M_TOKEN")

# This sets the Authorization header like the curl example
headers = {
    "Authorization": S3M_TOKEN,
}

response = requests.delete(
    S3M_BASE_PATH + "/revoke",
    headers=headers,
)

if response.ok:
    token_response = response.json()
    print(token_response)

else:
    raise ValueError("Request to S3M failed")

Response: HTTP 200 with empty body {}

You can also revoke tokens via the myOLCF Manage Tokens interface.

Introspect a Token

Retrieve details about the current token including its permissions, expiration, and associated project.

GET /olcf/v1/token/ctls/introspect

curl

curl -H @.env \
    https://s3m.olcf.ornl.gov/olcf/v1/token/ctls/introspect

Python

from s3m_apis_betterproto.tms.v1 import IntrospectAuthTokenRequest

client = factory.create_client(TokenControlStub)
info = await client.introspect_auth_token(IntrospectAuthTokenRequest())

Go

import (
    "context"
    tmspb "s3m.olcf.ornl.gov/apis/tms/v1"
)

client := tmspb.NewTokenControlClient(conn)
info, err := client.IntrospectAuthToken(context.Background(), &tmspb.IntrospectAuthTokenRequest{})

Python (requests)

import os
import requests

S3M_BASE_PATH = "https://s3m.olcf.ornl.gov/olcf/v1/token/ctls"
S3M_TOKEN = os.getenv("S3M_TOKEN")

# This sets the Authorization header like the curl example
headers = {
    "Authorization": S3M_TOKEN,
}

response = requests.get(
    S3M_BASE_PATH + "/introspect",
    headers=headers,
)

if response.ok:
    token_response = response.json()
    print(token_response)

else:
    raise ValueError("Request to S3M failed")

Response:

{
  "token": {
    "username": "stf040_auser",
    "project": "STF040",
    "plannedExpiration": "2024-11-08T14:45:38.756330Z",
    "securityEnclave": "open",
    "description": "docs-example-01",
    "oneTimeToken": false,
    "delayedStart": false,
    "delayDate": ""
  }
}

Token Structure

OLCF Project Access Tokens are JWTs. The payload conveys basic metadata, but the full capabilities are only available via the introspection API above.

JWT Payload Fields:

{
  "description": "docs-example-01",
  "type": "opat",
  "aud": ["api.olcf.ornl.gov"],
  "nbf": 1730990738,
  "iat": 1730990738,
  "jti": "9aaa44e6-f370-42f9-aafa-895994d44411"
}

Field	Description
`description`	User-provided description when token was created
`type`	Token type (`opat` = OLCF Project Access Token)
`aud`	Intended audience for the token
`nbf`	Not valid before (Unix timestamp)
`iat`	Issued at (Unix timestamp)
`jti`	Unique token identifier (UUID)

Introspection Response Fields:

Field	Description
`username`	The project user account (`{project}_auser`)
`project`	Associated OLCF project
`plannedExpiration`	When the token will expire (ISO 8601)
`securityEnclave`	Security classification (e.g., `open`)
`oneTimeToken`	If true, token can only be used once
`delayedStart`	If true, token activation was delayed
`delayDate`	When the delayed activation will begin (ISO 8601)