Authorization and token
Environment variables, curl, and token expiration.
This page describes how to obtain an access token and pass it in requests to the Shturval Backend API (basePath /api/v1 in OpenAPI). The interactive specification declares the Bearer scheme in securityDefinitions: the token goes in the Authorization header.
Prepare environment variables
export SH_USERNAME="admin"
export SH_PASS="my-password"
export CLUSTERNAME=my-cluster
export INGRESS="$CLUSTERNAME.ip-x-x-x-x.shturval.link"
export AUTHENDPOINT="https://shturval.$INGRESS/authn"
export BACKENDPOINT="https://shturval.$INGRESS"
export CLIENT_SECRET="clientsecret"
export COOKIE_PATH=/tmp/cookie
Tip: CLIENT_SECRET is the client_secret value from the backend-* Secret in the shturval-backend namespace. If you do not have access, ask your administrator.
BACKENDPOINT is the base URL to which you append the API path, for example $BACKENDPOINT/api/v1/clusters.
Obtain a token
API access uses an access token obtained through the OAuth flow of an internal or external (OIDC) authentication provider.
# Authentication
curl -k -v -s $AUTHENDPOINT/login -c $COOKIE_PATH \
--data-urlencode "username=$SH_USERNAME" \
--data-urlencode "password=$SH_PASS" &>/dev/null
# Obtain authorization code
code=$(curl -k -b $COOKIE_PATH -v "$AUTHENDPOINT/oauth/authorize?response_type=code&client_id=backend&expired=48h&redirect_uri=localhost/cb" 2>&1 | grep -E -o "\<code=[A-Z0-9]+")
# Obtain access token
token=$(curl -k -s "$AUTHENDPOINT/oauth/token" \
--header 'Content-Type: application/x-www-form-urlencoded' \
-b $COOKIE_PATH \
--data-urlencode 'client_id=backend' \
--data-urlencode "client_secret=$CLIENT_SECRET" \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode "$code" \
--data-urlencode "redirect_uri=localhost/cb" | jq -r '.access_token')
Using the token
Send all API requests with this header:
Authorization: Bearer <token>
In addition to the token, the call typically requires appropriate permissions (see Swagger for operation descriptions).
Token lifetime
By default, the token is valid for 24 hours. To extend the period (for example, to 48 hours) when requesting an authorization code, add the expired=48h parameter:
$AUTHENDPOINT/oauth/authorize?response_type=code&client_id=backend&expired=48h&redirect_uri=localhost/cb
For more information about setting token lifetime, see Token lifetime.