Authentication

The Portal Backend API and the Dataset Payload APIs accept OAuth2 access tokens from KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs.. Send the token as a Bearer token in the Authorization header. The APIs do not accept a browser session or an ID token.

The APISIXApache APISIXAn open-source API gateway for traffic management, security and observability. In CIVITAS/CORE it is used as the centralized entrypoint to route and protect externally exposed APIs. gateway checks every token. It accepts only tokens that the api-access KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. client issues. A token from the portal login gets 401 Unauthorized.

At this time, you get a token only with the api-access client and user credentials. The next release adds support for more authentication methods.

Obtain an access token

Request the token from the KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. realm of your instance. To find <realm>, open the portal sign-in page: the realm is the part after /realms/ in the URL. Use the api-access client with the password grant. The client is public, so the request needs no client secret.

curl --request POST \
  "https://idm.<your-domain>/realms/<realm>/protocol/openid-connect/token" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "client_id=api-access" \
  --data-urlencode "username=<username>" \
  --data-urlencode "password=<password>"

If the user has TOTP configured, also send the current six-digit one-time code:

  --data-urlencode "otp=<six-digits>"

The token is in the access_token field of the response. To save the token in a shell variable, add --silent to the command and pipe the output to jq:

TOKEN=$(curl --silent --request POST ... | jq -r .access_token)

The api-access client issues no refresh token. When the token expires, request a new one.

The APIs apply the permissions of the user who requested the token. The default deployment has no client for the Authorization Code flow or the client credentials flow for API use. The security scheme in the OpenAPI reference names the Authorization Code flow because the portal uses it to sign in.

Send the Bearer token

Send the token in the Authorization header of each request:

Authorization: Bearer <access_token>

For example, GET /v1/users/me on the Portal Backend API returns the calling user. It needs no permission, but it returns 403 Forbidden when the platform has no record of the user:

curl --request GET \
  "https://management.<your-domain>/v1/users/me" \
  --header "Authorization: Bearer <access_token>" \
  --header "Accept: application/json"

A valid token can still get 403 Forbidden when the user does not have the permission for the request.