Appearance
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=$PASSWORDpython
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_TOKENThe 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