Skip to contents

Set your credentials

Source: vignettes/articles/set-your-credentials.Rmd
set-your-credentials.Rmd

Setting your credentials

This guide outlines how to set your credentials for accessing data from a DHIS2 instance. DHIS2 (District Health Information System 2) is a widely used open-source platform for health data management.To access the data through the khisr package, you need to provide valid credentials.

The khisr package cannot make calls to DHIS2 without credentials, and incorrect credentials will result in an unauthorized error from DHIS2.

This method is recommended for security reasons as it avoids storing credentials directly in your code.

khis_cred(config_path = "/path/to/the/JSON/file.json")

The JSON file should have the following format:

{
  "credentials": {
    "username": "your-dhis2-username",
    "password": "your-dhis2-password",
    "server": "https://<dhis2 api instance>"
  }
}

Alternative Method: Direct Input

If you cannot use a JSON file, you can provide your username and password directly:

khis_cred(username = 'your_username', password = 'your_password', server = 'https://<dhis2 api instance>')

Personal Access Tokens

DHIS2 also supports Personal Access Tokens as an alternative to username/password, and recommends them over Basic Authentication for scripts and integrations — since a token can be scoped and revoked independently of your account password. Generate one from your DHIS2 account settings (or POST /api/apiToken), then use it in place of username/password, either directly:

khis_cred(token = 'd2pat_...', server = 'https://<dhis2 api instance>')

or via the JSON configuration file, using token instead of username/password:

{
  "credentials": {
    "token": "d2pat_...",
    "server": "https://<dhis2 api instance>"
  }
}

token cannot be combined with username/password — provide one or the other. When authenticating with a token, [khis_username()] returns NULL, since a token isn’t tied to a username the way Basic Authentication is.

Additional Functions

  • khis_has_cred(): Confirms that your credentials have been set successfully.
  • khis_username(): Retrieves the username of the currently logged-in user (NULL when using a token).
  • khis_display_name(): Retrieves the display name of the currently logged-in user.
  • khis_base_url(): Retrieve the base url of the DHIS2 instance being used.
  • khis_api_version(): Retrieve the DHIS2 API version requests are pinned to, if any (see api_version in [khis_cred()]).
  • khis_cred_clear(): Clears the credentials of the currently logged-in user.