Nabla Connect is intended to be used by your backend systems, allowing them to authenticate and interact with the 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.

<aside> <img src="/icons/info-alternate_lightgray.svg" alt="/icons/info-alternate_lightgray.svg" width="40px" />

The <baseUrl> for all APIs is [https://<region>.api.nabla.com/v1/connect/server](https://app.nabla.com/api/<REGION>/v1/connect/server)
<region> is us or eu

</aside>

<aside> 📝

• Sample JavaScript code to fetch the OAuth token </aside>

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, split between the header and body:

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. The kid corresponds to the key ID in the JWKS, ensuring the correct key is used to validate the JWT.