Personal Access Tokens

Personal Access Tokens (PAT)

Personal Access Tokens let a user obtain a long-lived bearer token they can paste into a script or workflow engine so it can call the REST API on their behalf — without embedding a password or going through the interactive login flow.

A token is created either by the user (as a process) or by an administrator (via the CLI launcher), has a configurable, capped expiry, and can be revoked at any time.

Sources: issue ufal/clarin-dspace#1259, PR ufal/clarin-dspace#1260. Shipped in Release Notes § 2026.1.

How it works

• A token is a JWT (HS256-signed, then JWE-encrypted). The token carries the eperson id, issuer, and expiration as claims.
• The database (clarin_token table) stores only an id, the owning eperson_id, and a per-token signing key (sign_key) — not the token string itself. The token is only ever shown once, at creation time.
• On each request, JWTTokenRestAuthenticationServiceImpl inspects the Authorization: Bearer … header. If the value parses as a CLARIN token, it looks up the matching clarin_token row by the key id embedded in the token, verifies the signature, issuer, owner, and that the token has not expired, then authenticates the request as that eperson (authentication method clarin-token).
• Because authentication resolves to the eperson directly, special groups assigned by other mechanisms (e.g. IP-based or Shibboleth-attribute groups) are not applied to token requests. The user gets only the access that comes from their account's persistent group memberships.

Configuration

Set these in local.cfg (see Release Notes § 2026.1 and Configuration):

Property	Default	Description
clarin.token.encryption.secret	(none)	Required to use PAT. Base64-encoded AES key used to encrypt/decrypt tokens. Generate it with dspace clarin-token -g.
clarin.token.max.expiration.time.in.days	90	Maximum allowed token lifetime. Create requests asking for a longer expiry are rejected.

Generate the encryption secret once and keep it stable — rotating it invalidates all existing tokens:

/dspace/bin/dspace clarin-token -g
# Encryption Key: Y3J5eYoHzKIA21pLzpZpM1yzwwwg4kxK1HCODOKlcvU=

Copy the value into clarin.token.encryption.secret.

Creating and managing tokens

There are two entry points with different option sets:

As a user — the clarin-token process

Regular users create and revoke their own tokens by running the clarin-token process (Admin/process UI, or the scripts-and-processes REST endpoint). The created token is emailed to the user (or to an address passed with -e); the process output also shows it.

Option	Meaning
-c, --create	Create a new token
-d, --delete	Delete/deactivate a token
-x, --expiration	Expiry as days or hours, e.g. 3d or 48h — required for create
-e, --email	E-mail address to send the new token to (optional for create)
-t, --token	Token to delete/deactivate — required for delete
-h, --help	Help

As an administrator — the dspace clarin-token launcher command

Administrators manage tokens for any user (selected by UUID or email) from the command line:

/dspace/bin/dspace clarin-token …

Option	Meaning
-c, --create	Create a token for the eperson given by -u or -e
-d, --delete	Delete a specific token (-t), all tokens for an eperson (-u/-e), or — with none of those — all tokens
-g, --generateEncryptionKey	Generate a secret key for clarin.token.encryption.secret
-u, --ePerson_ID	eperson UUID
-e, --email	eperson email
-x, --expiration	Expiry as days or hours (e.g. 3d, 48h) — required for create
-t, --token	Token string (optional for delete)
-h, --help	Help

Examples (admin launcher)

# Create a token for a user (by email) that expires in 48 hours
/dspace/bin/dspace clarin-token -c -x 48h -e testuser@email.com

# Create a token for a user (by UUID) that expires in 20 days
/dspace/bin/dspace clarin-token -c -x 20d -u 83352ca0-ae1e-4c5c-8e5c-dfee985f1003

# Delete/deactivate a single token
/dspace/bin/dspace clarin-token -d -t eyJ...Nw

# Delete all tokens for a user (by email)
/dspace/bin/dspace clarin-token -d -e testuser@email.com

# Delete all tokens for a user (by UUID)
/dspace/bin/dspace clarin-token -d -u 83352ca0-ae1e-4c5c-8e5c-dfee985f1003

# Delete ALL tokens (no -t/-u/-e)
/dspace/bin/dspace clarin-token -d

Using a token

Pass the token in the Authorization header using the Bearer scheme:

curl -H "Authorization: Bearer eyJ...Nw" https://<your-repo>/server/api/…

Notes & caveats

• The expiry is capped at clarin.token.max.expiration.time.in.days; there are no never-expiring tokens.
• Token requests do not receive IP-based or other dynamically-assigned special groups — grant access via the user's persistent group memberships instead.
• The plaintext token is shown only at creation. If lost, revoke it and create a new one.

See also

• All Features § Personal Access Tokens
• Configuration
• Release Notes § 2026.1