Overview

Introduction

Flow overview

Requirements

Versionning

Authentication

Server authentication

Incoming APIs

Overview

Provision user

Create encounter

Refresh encounter URL

Outgoing APIs

Overview

Callback authentication

Response protocol

Callback types

Reference

Changelog

Nabla Connect is intended to be used by your backend systems, allowing them to authenticate and interact with Nabla. Authentication for Nabla Connect follows the OAuth 2.0 client credentials flow with JWT-based client assertions.

1. Creating an OAuth Client

An OAuth Client is the entity that authenticates with Nabla Connect on behalf of your backend system. The OAuth Client is responsible for securely managing authentication credentials. To start, you'll need to create an OAuth Client in the Nabla Connect Admin. When doing so, you should provide either of the two following options:

• JWKS URL: This is the preferred method because it allows for seamless key rotation. A JWKS (JSON Web Key Set) URL hosts one or more public keys, enabling Nabla to validate tokens using the correct key. If your keys change, you can simply update the response of your JWKS endpoint without reconfiguring your OAuth Client.

  How to Obtain a JWKS URL?

  If you don't already have a JWKS, you can expose one by setting up a service that hosts your public keys in the JWKS format.

  Cloud services like AWS Cognito, Google Identity Platform and Auth0 can help you automatically generate and expose your keys as a JWKS.

• Public Key (static): Alternatively, you can provide a static public key in X.509 format (base64-encoded). This is a less flexible approach since key rotation would require updating the configuration in the Nabla Connect Admin. In this specific case, only RSA 256 Algorithm is accepted. You can generate a pair of public/private RSA keys using the following commands:

  1. Generate the private key: openssl genpkey -algorithm RSA -out private_key.pem
  2. Extract the public key from the private one: openssl rsa -pubout -in private_key.pem -out public_key.pem

  You should then provide Nabla with the public key for OAuth Client creation, i.e. the public_key.pem file content that starts with -----BEGIN PUBLIC KEY-----.

Upon creation, copy the OAuth Client's UUID to reference it when constructing the JWT Client Assertion.

Regularly rotate the OAuth keys

It's critical to regularly rotate your keys to maintain the security of your integration. If you choose the JWKS URL option, rotating keys is easier because you can update the keys at your endpoint without any downtime. With a static public key, you'll need at each rotation to manually create a new OAuth Client, migrate your assertion building and signing, then after a certain migration period manually delete the old OAuth Client.

2. Fetching the OAuth token

ℹ️ The <baseUrl> for all APIs is https://<region>.api.nabla.com/v1/connect/server — <region> is us or eu

• Sample JavaScript code to fetch the OAuth token

1. Constructing a JWT Client Assertion

The client assertion is a one-time JWT used to authenticate your request to the <baseUrl>/oauth/token endpoint. The JWT must include the following claims:

In the JWT header

• alg (Algorithm): Must be set to RS256.
• typ (Type): Must be set to JWT.
• kid (key ID): Required if your OAuth Client uses a JWKS URL.

In the JWT body

• sub (subject): The OAuth Client's UUID.
• iss (issuer): Same as sub, i.e., the OAuth Client's UUID.
• aud (audience): The full URL of the token endpoint (<base url>/oauth/token).
• exp (expiration time): Must not be in the past and no further than 5 minutes in the future.
• iat (issued at): Optional, but if included, must be within 5 minutes of exp.
• jti (JWT ID): Optional but highly recommended — prevents reuse of the same JWT.

For constructing and signing JWTs, you can use open source libraries from Auth0, notably java-jwt for Java. See also RFC7523.

2. Requesting a Server Access Token

POST /oauth/token
{
  "grant_type": "client_credentials",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "<your JWT here>"
}

Response:

{ "access_token": "<JWT_ACCESS_TOKEN>", "expires_in": 3600 }

The expiration time is typically set to 1 hour, but it might be subject to change without prior notice.

3. Handling Token Expiry

When your server access token expires or approaches expiry, simply repeat the authentication process by generating a new JWT client assertion and calling the <baseUrl>/oauth/token endpoint again.