Authenticate NocoDB HTTP request

Adds an authentication header to an HTTP request intended to call a NocoDB API endpoint. The following credential sources are consulted in descending order and the first one applicable is used:

1. If api_token is provided, it is directly added to the request as xc-token header.

2. If email is provided, the corresponding user has signed in before in the current R session and the generated access token is not yet expired, it is re-used.

3. If email is provided, the corresponding user has signed in before in a past R session and hence there's a cached refresh token available which is not yet expired, it's used to generate a fresh access token.

4. If email and password are provided, they are used to newly sign_in() the corresponding user.

Access tokens (sources 2–4 above) are added to the request as xc-auth header. Other than the api_token, they expire after a certain amount of time, configured by the NocoDB server via NC_JWT_EXPIRES_IN (defaults to 10 hours).

Usage

req_auth(
  req,
  email = pal::pkg_config_val("email"),
  password = pal::pkg_config_val("password"),
  api_token = pal::pkg_config_val("api_token")
)

Arguments

req

A httr2 request object.

email

E-mail address of the NocoDB user to authenticate with.

password

Password of the NocoDB user to authenticate with.

api_token

NocoDB API token. Takes precedence over email and password if provided.

Value

A modified HTTP request.

Invalid token errors

• If you did provide an api_token and encounter an Invalid token error, it simply means the api_token is invalid (e.g. because it was revoked).

• If you did not provide an api_token and encounter an Invalid token error, it means the access token generated by the last call to sign_in() in the current R session has expired or was revoked meanwhile. This should only happen in rare edge cases since expired access tokens aren't re-used by req_auth().

• If you encounter an Invalid refresh token error, it means the refresh token cached to disk by the last call to sign_in() in a past R session has expired meanwhile. This should only happen in rare edge cases since expired refresh tokens aren't re-used by req_auth().

The latter two errors should resolve by manually invoking sign_in().

If you would like to avoid token expiration errors altogether, consider using an API token (api_token) instead of email and password.

See also

Other common functions: api(), req_basic()

Other functions to manage NocoDB authentication: api_tokens(), assert_super_admin(), create_api_token(), delete_api_token(), is_signed_in(), is_super_admin(), refresh_sign_in(), sign_in(), sign_out(), sign_up_user()