Skip to content

Authentication

Using authentication at performing requests to u-Slicer via API

Authentication is performed in each request and is implemented by specifying a proper access token. At using the curl utility access token can be specified in two methods:

  1. In the Authorization header (Recommended).

    -H "Authorization: Bearer <token>"

  2. As the token key in Post arguments (Supported for compatibility).

    "token": "<token>"

Receiving an access token

Access tokens are issued by the OIDC provider (Keycloak) configured for your u-Slicer deployment. Request one with the password grant, using your u-Slicer credentials.

Two values are specific to the deployment:

  • issuer_url: the OIDC realm URL. Ask your u-Slicer administrator.
  • client_id: returned by the GET /API/v2/config method as openid_auth_client_id. It is a public client, so no client secret is needed.
curl --data "grant_type=password" \
--data "client_id=<client_id>" \
--data "username=<username>" \
--data "password=<password>" \
--data-urlencode "scope=openid email profile" \
"<issuer_url>/protocol/openid-connect/token"

The response contains the token to use in the Authorization header:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6..."
}

The scope must include email and profile, otherwise the token carries no user details and API methods return incomplete user information.

Refreshing an access token

Access tokens are short-lived (expires_in, in seconds). To get a new one without re-sending credentials, use the refresh_token from the previous response:

curl --data "grant_type=refresh_token" \
--data "client_id=<client_id>" \
--data "refresh_token=<refresh_token>" \
"<issuer_url>/protocol/openid-connect/token"

The response has the same format as above, and it contains a new refresh_token: store it and use that one for the next refresh.