Once you have the BYO sidecar up and running, the next step is to set up your backend to interact with the sidecar.

1. Install the client library for your backend language. Don’t see your language? Let us know.

   Node Python Java .NET

   npm install @propelauth/byo-node

   pip install propelauth-byo

   implementation 'com.propelauth:propelauth-byo:1.0.0'

   dotnet add package PropelAuthByo.Client

             npm install @propelauth/byo-node
           

             pip install propelauth-byo
           

             implementation 'com.propelauth:propelauth-byo:1.0.0'
   
           

             dotnet add package PropelAuthByo.Client
   
           

2. Create an integration key for your application in the PropelAuth BYO dashboard. This is done by clicking the Gear Icon in the top right corner, selecting “Manage Settings”, and then navigating to the “Integration Keys” tab. Alternatively, you can programmatically create an integration key.

   

   After creating the key, make sure to copy the generated key as you will need it to initialize the client library in your application.

3. Initialize the client library in your application using the integration key you just created.

   Node Python Java .NET

   import { createClient } from "@propelauth/byo-node";
   
   const client = createClient({
       url: 'http://localhost:2884', // Default sidecar URL
       integrationKey: 'api_...'
   });

   from propelauth_byo import create_client
   
   client = create_client(
       url='http://localhost:2884',  # Default sidecar URL
       integration_key='api_...'
   )

   import com.propelauth.client.PropelAuthClient;
   
   PropelAuthClient client = PropelAuthClient.create(
       "http://localhost:2884", // Default sidecar URL
       "api_..."
   );

   using PropelAuth.Client;
   
   var client = new PropelAuthClient(new PropelAuthOptions
   {
       Url = "http://localhost:2884", // Default sidecar URL
       IntegrationKey = "api_..."
   });

             import { createClient } from "@propelauth/byo-node";
   
   const client = createClient({
       url: 'http://localhost:2884', // Default sidecar URL
       integrationKey: 'api_...'
   });
           

             from propelauth_byo import create_client
   
   client = create_client(
       url='http://localhost:2884',  # Default sidecar URL
       integration_key='api_...'
   )
   
           

             import com.propelauth.client.PropelAuthClient;
   
   PropelAuthClient client = PropelAuthClient.create(
       "http://localhost:2884", // Default sidecar URL
       "api_..."
   );
   
           

             using PropelAuth.Client;
   
   var client = new PropelAuthClient(new PropelAuthOptions
   {
       Url = "http://localhost:2884", // Default sidecar URL
       IntegrationKey = "api_..."
   });
   
           

   In production, you’ll likely want to use environment variables or a secrets manager for your URL and integration key instead of hardcoding them.

4. To ensure that the client is working correctly you can run a simple test to check if it can communicate with the sidecar. This can be done by calling the ping method from the client library.

   Node Python Java .NET

   const ping = await client.ping({});
   console.log(ping);
   // Output: { ok: true, data: { timestamp: 1753197674 }}

   ping = await client.ping()
   print(ping)
   # Output: Ok(data=PingResponse(timestamp=1753197674), ok=True)

   PingResponse ping = client.ping(new PingCommand());
   System.out.println(ping);
   // Output: PingResponse(timestamp=1753197674)

   var ping = await client.PingAsync(new PingCommand());
   Console.WriteLine(ping);
   // Output: PingResponse { Timestamp = 1753197674 }

             const ping = await client.ping({});
   console.log(ping);
   // Output: { ok: true, data: { timestamp: 1753197674 }}
           

             ping = await client.ping()
   print(ping)
   # Output: Ok(data=PingResponse(timestamp=1753197674), ok=True)
   
           

             PingResponse ping = client.ping(new PingCommand());
   System.out.println(ping);
   // Output: PingResponse(timestamp=1753197674)
   
           

             var ping = await client.PingAsync(new PingCommand());
   Console.WriteLine(ping);
   // Output: PingResponse { Timestamp = 1753197674 }
   
           

(Optional) Programmatically Generate an Integration Key

During initial setup, you can programmatically generate an integration key by following the steps below:

1. Add an INITIAL_SETUP_SECRET environment variable to BYO. This must be at least 16 characters long.

2. Make the following request to BYO (default domain is http://localhost:2884):

   This endpoint only works for the first key that you create - it's designed to be used during initial setup and not afterwards. Include a `x-setup-secret` header with the value you set for the `INITIAL_SETUP_SECRET` environment variable.

   Arguments

   name string required

   Name of the integration key.

   permissions string / object required

   Can equal either "FullAccess" (string) or an object with selective permissions. If selective permissions are used, this type becomes an object with the following fields:

   • passkeys: Can equal either "Full", "ReadOnly", or "None".
   • sessions: Can equal either "Full", "ReadOnly", or "None".
   • scim: Can equal either "Full", "ReadOnly", or "None".
   • sso: Can equal either "Full", "ReadOnly", or "None".
   • impersonation: Can equal either "Full", "ReadOnly", or "None".

   description string

   Description of the integration key.

   expires_at number

   Unix timestamp for when the key should expire. If not specified, the key will never expire.

   cURL

   curl --location --request POST 'http://localhost:2884/api/initial_setup' \
   --header 'x-setup-secret: <INITIAL_SETUP_SECRET>' \
   --header 'Content-Type: application/json' \
   --data '{
       "name": "My Integration Key",
       "description": "My BYO Integration Key",
       "permissions": {
           "SelectiveAccess": {
               "passkeys": "ReadOnly",
               "sessions": "Full",
               "scim": "None",
               "sso": "ReadOnly",
               "impersonation": "None"
           }
       },
       "expires_at": 1782149282
   }'

3. The response will include the generated integration key:

   {
       "id": "EaOzePz...",
       "integrationKey": "api_EaOzePz..."
   }

Next Steps

And you’re all set! The PropelAuth BYO client is now installed and ready to use in your application. You can start integrating PropelAuth BYO features such as Passkey support, Session Management, and more.