Skip to content

Authentication ​

The Transkribus API uses the OpenID Connect protocol. Authenticate with your Transkribus account credentials to obtain an access token, and send it as a Bearer token in every API request. API access needs an account on the Scholar plan or above.

OpenID Connect configuration: https://account.readcoop.eu/auth/realms/readcoop/.well-known/openid-configuration

Replace $USERNAME and $PASSWORD with your Transkribus credentials. The client_id is processing-api-client.

1. Get an access token ​

bash
curl -X POST https://account.readcoop.eu/auth/realms/readcoop/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode grant_type=password \
  --data-urlencode client_id=processing-api-client \
  --data-urlencode username=$USERNAME \
  --data-urlencode password=$PASSWORD
python
import requests

TOKEN_URL = "https://account.readcoop.eu/auth/realms/readcoop/protocol/openid-connect/token"

tokens = requests.post(TOKEN_URL, data={
    "grant_type": "password",
    "client_id": "processing-api-client",
    "username": USERNAME,
    "password": PASSWORD,
}).json()
ACCESS_TOKEN = tokens["access_token"]
REFRESH_TOKEN = tokens["refresh_token"]
js
const TOKEN_URL = "https://account.readcoop.eu/auth/realms/readcoop/protocol/openid-connect/token";

const tokens = await fetch(TOKEN_URL, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "password",
    client_id: "processing-api-client",
    username: USERNAME,
    password: PASSWORD,
  }),
}).then((r) => r.json());
const ACCESS_TOKEN = tokens.access_token;
const REFRESH_TOKEN = tokens.refresh_token;

The response is JSON. access_token is what you send; expires_in says for how many seconds it is valid; refresh_token gets you a new one without the password.

json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "scope": "openid email profile"
}

Send it on every API request as Authorization: Bearer $ACCESS_TOKEN. A request with a missing or expired token gets a 401; refresh the token and retry, see Errors. The lifetimes above are examples: read expires_in from your own response and refresh before it runs out.

2. Refresh the access token ​

bash
curl -X POST https://account.readcoop.eu/auth/realms/readcoop/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode client_id=processing-api-client \
  --data-urlencode refresh_token=$REFRESH_TOKEN

The response has the same shape as in step 1, with a new access_token and a new refresh_token.

3. End the session ​

bash
curl -X POST https://account.readcoop.eu/auth/realms/readcoop/protocol/openid-connect/logout \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode client_id=processing-api-client \
  --data-urlencode refresh_token=$REFRESH_TOKEN

Transkribus Developer Platform