The restAPI auth endpoints#

The API supports token-based authentication using OAuth2. To obtain an access token, clients can use the /api/freva-nextgen/auth/v2/token endpoint by providing valid username and password credentials. The access token should then be included in the authorization header for secured endpoints.

POST /api/freva-nextgen/auth/v2/token#

Create an new login token from a username and password. You should either set a username and password or an existing refresh token. You can also set the client_id. Client id’s are configured to gain access, specific access for certain users. If you don’t set the client_id, the default id will be chosen.

Form Parameters:

code – The code received as part of the OAuth2 authorization code flow
redirect_uri – The URI to which the authorization server will redirect the user after authentication. It must match one of the URIs registered with the OAuth2 provider
refresh-token – The refresh token that is used to create a new token the refresh token can be used instead of authorizing via user creentials.
client_id – The unique identifier for your application used to request an OAuth2 access token from the authentication server, this form parameter is optional.

Status Codes:

200 OK – no error
401 Unauthorized – unauthorized

Response Headers:

Content-Type – application/json: access and refresh token.

Example Request#

POST /api/freva-nextgen/auth/v2/token HTTP/1.1
host: www.freva.dkrz.de

{
    "refresh-token": "my-token",
}

Example Response#

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6.."
    "token_type": "Bearer",
    "expires": 1722874908,
    "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIi.."
    "refresh_expires": 1722876408,
    "scope": "profile email address",
}

Code examples#

Below you can find example usages of this request in different scripting and programming languages

Shell
Python
gnuR
Julia
C/C++

curl -X POST https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/token \
 -d "username=janedoe" \
 -d "password=janedoe123"

import requests
response = requests.post(
  "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/token",
  data={"refresh-token": "mytoken"}
)
token_data = response.json()

library(httr)

url <- "https://freva.dkrz.de/api/freva-nextgen/auth/v2/token"
response <- POST(
   "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/token",
   body = setNames(list("mytoken"), "refresh-token"),
   encode = "form"
)
token_data <- content(response, "parsed")

using HTTP
using JSON

response = HTTP.POST(
  "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/token",
  body = Dict("refresh-token" => "mytoken")
)
token_data = JSON.parse(String(response.body))

#include <stdio.h>
#include <curl/curl.h>

int main() {
    CURL *curl;
    CURLcode res;

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();
    if(curl) {
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Content-Type: application/x-www-form-urlencoded");

        curl_easy_setopt(curl, CURLOPT_URL, "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/token");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "refresh-token=mytoken");

        res = curl_easy_perform(curl);
        curl_easy_cleanup(curl);
    }
    curl_global_cleanup();
    return 0;
}

—

GET /api/freva-nextgen/auth/v2/status#

Check the status of an access token.

Request Headers:

Authorization – The OAuth2 access token

Status Codes:

200 OK – no error
401 Unauthorized – unauthorized

Response Headers:

Content-Type – application/json: access and refresh token.

Example Request#

POST /api/freva-nextgen/auth/v2/status HTTP/1.1
host: www.freva.dkrz.de
Authorization: Bearer your_access_token

Example Response#

HTTP/1.1 200 OK
Content-Type: application/json

{
    "sub": "648692af-aaed-4f82-9f74-2d6baf96f5ea",
    "exp": 1719261824,
    "email": "jane@example.com"
}

Code examples#

Below you can find example usages of this request in different scripting and programming languages

Shell
Python
gnuR
Julia
C/C++

curl -X GET https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/status \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests
response = requests.get(
  "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/status",
  headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
)
token_data = response.json()

library(httr)

response <- GET(
   "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/status",
   add_headers(Authorization = paste("Bearer", "YOUR_ACCESS_TOKEN"))
)
token_data <- content(response, "parsed")

using HTTP
using JSON

response = HTTP.get(
  "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/status",
  headers = Dict("Authorization" => "Bearer YOUR_ACCESS_TOKEN")
)
token_data = JSON.parse(String(response.body))

#include <stdio.h>
#include <curl/curl.h>

int main() {
    CURL *curl;
    CURLcode res;

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();
    if(curl) {
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Authorization: Bearer YOUR_ACCESS_TOKEN");

        curl_easy_setopt(curl, CURLOPT_URL, "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/status");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

        res = curl_easy_perform(curl);
        curl_easy_cleanup(curl);
    }
    curl_global_cleanup();
    return 0;
}

—

GET /api/freva-nextgen/auth/v2/userinfo#

Get userinfo for the current token.

Request Headers:

Authorization – The OAuth2 access token

Status Codes:

200 OK – no error
401 Unauthorized – unauthorized

Response Headers:

Content-Type – application/json: access and refresh token.

Example Request#

POST /api/freva-nextgen/auth/v2/userinfo HTTP/1.1
host: www.freva.dkrz.de
Authorization: Bearer your_access_token

Example Response#

HTTP/1.1 200 OK
Content-Type: application/json

{
    "username": "janedoe",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com"
    "home": ""
    "is_guest": true
}

Code examples#

Below you can find example usages of this request in different scripting and programming languages

Shell
Python
gnuR
Julia
C/C++

curl -X GET https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/userinfo \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests
response = requests.get(
  "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/userinfo",
  headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
)
token_data = response.json()

library(httr)

response <- GET(
   "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/userinfo",
   add_headers(Authorization = paste("Bearer", "YOUR_ACCESS_TOKEN"))
)
token_data <- content(response, "parsed")

using HTTP
using JSON

response = HTTP.get(
  "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/userinfo",
  headers = Dict("Authorization" => "Bearer YOUR_ACCESS_TOKEN")
)
token_data = JSON.parse(String(response.body))

#include <stdio.h>
#include <curl/curl.h>

int main() {
    CURL *curl;
    CURLcode res;

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();
    if(curl) {
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Authorization: Bearer YOUR_ACCESS_TOKEN");

        curl_easy_setopt(curl, CURLOPT_URL, "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/userinfo");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

        res = curl_easy_perform(curl);
        curl_easy_cleanup(curl);
    }
    curl_global_cleanup();
    return 0;
}

—

GET /api/freva-nextgen/auth/v2/systemuser#

Get system information for the user in possession of the oauth token.

Request Headers:

Authorization – The OAuth2 access token

Status Codes:

200 OK – no error
401 Unauthorized – unauthorized

Response Headers:

Content-Type – application/json: access and refresh token.

Example Request#

POST /api/freva-nextgen/auth/v2/systemuser HTTP/1.1
host: www.freva.dkrz.de
Authorization: Bearer your_access_token

Example Response#

HTTP/1.1 200 OK
Content-Type: application/json

{
    "pw_name": "janedoe",
    "pw_passwd": "\*",
    "pw_uid": 1000,
    "pw_gid": 1001
    "pw_gecos": "Jane Doe",
    "pw_dir":  "/home/jane",
    "pw_shell": "/bin/zsh"
}

Code examples#

Below you can find example usages of this request in different scripting and programming languages

Shell
Python
gnuR
Julia
C/C++

curl -X GET https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/systemuser \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests
response = requests.get(
  "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/systemuser",
  headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
)
token_data = response.json()

library(httr)

response <- GET(
   "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/systemuser",
   add_headers(Authorization = paste("Bearer", "YOUR_ACCESS_TOKEN"))
)
token_data <- content(response, "parsed")

using HTTP
using JSON

response = HTTP.get(
  "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/systemuser",
  headers = Dict("Authorization" => "Bearer YOUR_ACCESS_TOKEN")
)
token_data = JSON.parse(String(response.body))

#include <stdio.h>
#include <curl/curl.h>

int main() {
    CURL *curl;
    CURLcode res;

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();
    if(curl) {
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Authorization: Bearer YOUR_ACCESS_TOKEN");

        curl_easy_setopt(curl, CURLOPT_URL, "https://www.freva.dkrz.de/api/freva-nextgen/auth/v2/userinfo");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

        res = curl_easy_perform(curl);
        curl_easy_cleanup(curl);
    }
    curl_global_cleanup();
    return 0;
}

—

Notes on Code-Based Auth Flow#

Code-based authentication is the only supported method since version 2505.1.0. It follows the OAuth2 Authorization Code Flow and is suitable for both end users and Service Provider (SP) integrations. However, there are important guidelines and limitations you should be aware of.

🔒 In most cases: Do not call `/login` or `/callback` directly#

The endpoints /auth/v2/login and /auth/v2/callback are internal coordination points for the authentication process:

/login initiates the code flow by redirecting to the OpenID Connect provider.
/callback is the endpoint where the OpenID provider sends the authorization code.

These endpoints are not designed for direct use by end users or typical API consumers. Calling them directly will likely lead to errors or unexpected behaviour.

Instead, you should authenticate using one of the supported client tools:

The Python client: via freva_client.authenticate()
The CLI tool: via freva-client auth
The web portal: to manually log in and download a token file

These interfaces abstract away the complexity and ensure the flow is handled securely and correctly.

For Service Providers (SPs)#

If you are building a custom SP (e.g. a web service or interactive tool that needs to act on behalf of a user), then it is appropriate to interact with the code flow endpoints directly — but only with care.

Follow these steps:

Redirect the user to Freva’s /login endpoint:
```
GET /api/freva-nextgen/auth/v2/login?redirect_uri=https://your-sp.com/callback HTTP/1.1
host: www.freva.dkrz.de
```
- The redirect_uri must be a publicly accessible endpoint on your service that handles the code exchange.
User authenticates via the upstream Identity Provider (e.g., Keycloak).
The Identity Provider redirects back to your service’s /callback endpoint with a code and state query parameter.

Your SP must then POST the code to Freva’s token exchange endpoint:

POST /api/freva-nextgen/auth/v2/token HTTP/1.1
host: www.freva.dkrz.de
Content-Type: application/x-www-form-urlencoded

{
    code=XXX&redirect_uri=https://your-sp.com/callback
}

This will return a JSON with access token, refresh token, and expiry info.

Use the access token to authenticate future API requests.

Optionally refresh the token before expiry using:

POST /api/freva-nextgen/auth/v2/token HTTP/1.1
host: www.freva.dkrz.de
Content-Type: application/x-www-form-urlencoded

{
      grant_type=refresh_token&refresh_token=YYY
}

Note

You do not need to manage client secrets for browser-based SPs.
The redirect_uri must match one of the values registered with the OIDC provider.
If you are building a backend-for-frontend (BFF) architecture, handle the token exchange server-side to protect credentials.

This is the recommended approach for implementing a standards-compliant OAuth2 Authorization Code Flow as a Service Provider. A detailed example is given in the Integrating Authentiction into your Web Applications section.

The restAPI auth endpoints#

Example Request#

Example Response#

Code examples#

Example Request#

Example Response#

Code examples#

Example Request#

Example Response#

Code examples#

Example Request#

Example Response#

Code examples#

Notes on Code-Based Auth Flow#

🔒 In most cases: Do not call /login or /callback directly#

For Service Providers (SPs)#

🔒 In most cases: Do not call `/login` or `/callback` directly#