Skip to main content

Authorization

Follow this guide to create a new Avni credential that will allow Nexla to authenticate to and exchange data with your Avni account.
avni_api_auth.png

Avni

Prerequisites​

Avni's external API uses an OAuth 2.0 client-credentials (2-legged) flow against AWS Cognito (or Keycloak for on-premise deployments). The resulting JWT is sent to the Avni API on every request through the custom AUTH-TOKEN header (no Bearer prefix). Before creating a credential in Nexla, gather the following information from your Avni administrator or the Avni implementation team.

Identify Your Avni Deployment​

Avni can be reached via the Avni-hosted SaaS environments or a self-hosted Avni server. The values you need depend on your deployment:

  • Base URL — The Avni server endpoint. For Avni-hosted environments this is typically https://app.avniproject.org (production) or https://staging.avniproject.org (staging). Self-hosted deployments use the hostname configured for the Avni server.

  • Access Token URL — The OAuth 2.0 token endpoint of the identity provider that issues Avni JWTs. For AWS Cognito-backed Avni deployments this is the Cognito user-pool token endpoint, in the form https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token. For on-premise deployments backed by Keycloak, this is the Keycloak token endpoint in the form https://<keycloak-host>/auth/realms/<realm>/protocol/openid-connect/token.

  • Client ID and Client Secret — The OAuth 2.0 app-client credentials configured in the identity provider for machine-to-machine access to Avni. These are issued by the Avni implementation team for self-hosted deployments, or by your Avni implementation partner for SaaS deployments.

Request API Access from Avni​

The Avni public REST endpoints are intended for third-party integrations and are documented in the Avni API Guide. The internal endpoints used by the Avni mobile and web apps are not designed for integration and are not documented for external use — only the documented /api/* endpoints (subjects, enrolments, encounters, program encounters, tasks, datasets, segments, locations, notes) should be used.

  1. Contact the Avni team or your implementation partner to confirm that the external API is enabled for your organization and to request an OAuth 2.0 app client for machine-to-machine integrations. Avni issues a dedicated client ID and client secret for each integration so access can be audited and rotated independently.

  2. Provide the integration's purpose and the entities (subjects, enrolments, encounters, etc.) it needs to read or write so that appropriate permissions can be assigned. Avni's permission model is role-based — the user account associated with your OAuth app client must have access to the subject types, programs, and operations your integration requires.

  3. Confirm with your Avni administrator which Avni server (production, staging, or self-hosted) the integration should target, and note the corresponding Base URL.

Retrieve OAuth 2.0 Credentials​

Once Avni has provisioned an app client, retrieve the credential values:

  1. Obtain the Client ID and Client Secret from your Avni administrator (for AWS Cognito-backed deployments) or from the Keycloak admin console (for on-premise deployments). Store both values in a secure secret manager — the Client Secret is treated as a password and should never be committed to source control.

  2. Obtain the Access Token URL:

    • AWS Cognito-backed Avni: In the Cognito user pool, the token endpoint is shown under App integration > Domain as https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token. Your Avni administrator can provide this value.

    • Keycloak-backed Avni (on-premise): The token endpoint is exposed at https://<keycloak-host>/auth/realms/<realm>/protocol/openid-connect/token. The realm name is typically avni. Your Avni administrator can provide the exact value.

  3. Confirm the Base URL of the Avni server. The base URL must not include a trailing slash and must not include the /api path — Nexla appends the endpoint path automatically. For example, use https://app.avniproject.org, not https://app.avniproject.org/ or https://app.avniproject.org/api.

For complete information about the Avni external API and its authentication model, see the Avni API Guide and the Avni external API Swagger specification.

Important

The Client Secret grants programmatic access to your Avni organization's data. Store it in a secure secret manager, never commit it to source control, and rotate it immediately if you suspect it has been exposed. Coordinate rotation with your Avni administrator so the new secret can be provisioned in the identity provider.

Create an Avni Credential​

  • To create a new Avni credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

OAuth 2.0 Credential Settings​

Avni uses the OAuth 2.0 client-credentials (2-legged) flow. Nexla exchanges the Client ID and Client Secret for a JWT at the configured token URL, then sends the token to the Avni API on every request through the custom AUTH-TOKEN header.

  1. Enter the OAuth 2.0 Client ID issued for your Avni integration in the Client ID field. This value is the public identifier of the app client configured in AWS Cognito or Keycloak for machine-to-machine access to Avni.

  2. Enter the corresponding Client Secret in the Client Secret field. The client secret is treated as a password and is stored encrypted by Nexla.

  3. Enter the OAuth 2.0 token endpoint in the Access Token URL field. This is the URL Nexla calls to exchange the client ID and client secret for a JWT.

    • AWS Cognito-backed Avni: Use the Cognito user-pool token endpoint, for example https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token.

    • Keycloak-backed Avni (on-premise): Use the Keycloak token endpoint, for example https://<keycloak-host>/auth/realms/<realm>/protocol/openid-connect/token.

  4. Enter the Avni server endpoint in the Base URL field. This is the root URL of the Avni server, without a trailing slash and without the /api path. For example, enter https://app.avniproject.org for the Avni production environment, or the hostname of your self-hosted Avni server.

    Nexla appends the endpoint path (for example, /api/subjects or /api/encounters) to the base URL automatically when calling Avni. Do not include any path segments in the Base URL field.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential. Nexla automatically performs a test call against GET /api/locations?size=1 to verify that the OAuth flow succeeds and that the resulting JWT is accepted by the Avni server.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.