# Authentication

## Authenticating with Jua

To interact with Jua services and APIs, your application or client needs to be authenticated. This page outlines the available methods for providing your credentials.

We primarily use an API Key ID and an API Key Secret for authentication. You can generate these credentials from your Jua dashboard.

### Methods for Authentication

Choose the method that best suits your workflow and security requirements. Here's an overview, from the generally recommended to more specific use cases:

1. **Jua CLI**: For interactive sessions and local development.
2. **Using Environment Variables**: Set the key id and secret in the environment.
3. **Programmatic Configuration (Using `JuaClient`)**: Offers flexibility for various environments and dynamic setups.
4. **Global `api-key.json` File**: For system-wide configuration, use with caution.

***

#### 1. Jua CLI (`jua auth`)

The Jua Command Line Interface (CLI) will offer the simplest way to authenticate for many users, especially during local development and interactive use.

```bash
jua auth login
```

{% hint style="info" %}
Make sure you are already logged in the [developer portal](https://developer.jua.ai/)
{% endhint %}

This command will:

* Open a browser window, guiding you through the Jua authentication process.
* Store the obtained credentials locally (i.e. in a configuration file in your home directory, specific to the Jua CLI).
* Automatically make these credentials available to the Jua SDK and other CLI commands when run in the same user context.

***

#### 2. Environment Variables

1. **Obtain your Credentials:**
   * Navigate to the [API Keys section in your Jua dashboard.](https://developer.jua.ai/api-keys)
   * Generate a new API key, which will provide you with an `API Key ID` and an `API Key Secret`.
2. **Set the variables:**

   ```bash
   export JUA_API_KEY_ID="your_actual_api_key_id"
   export JUA_API_KEY_SECRET="your_actual_api_key_secret"
   ```

**Usage:** The Jua SDK will typically automatically detect and load credentials if they are found int the environment variables.

***

#### 3. Programmatic Configuration (Using `JuaClient`)

You can directly provide your authentication credentials when initializing the `JuaClient` in your Python code. This method offers maximum flexibility, especially for applications running in environments where `.env` files or a global CLI configuration are not suitable.

1. **Obtain your Credentials:**
   * Navigate to the [API Keys section in your Jua dashboard.](https://developer.jua.ai/api-keys)
   * Generate a new API key, which will provide you with an `API Key ID` and an `API Key Secret`.
2. **Pass credentials to `JuaClient`:**
   * **Directly in code (use with caution for hardcoded secrets):**

     ```python
     from jua import JuaClient

     settings = {
         "auth": {
             "api_key_id": "your_actual_api_key_id",
             "api_key_secret": "your_actual_api_key_secret"
         }
     }
     client = JuaClient(settings=settings)
     ```

     **Note:** Hardcoding secrets directly in your source code is generally discouraged for security reasons. Prefer loading them from environment variables or a secure vault.
   * **Pointing to an API Key JSON file:** You can store your API key ID and secret in a JSON file and provide the path to the `JuaClient`. Create a JSON file (e.g., `my_jua_key.json`):

     ```json
     {
         "api_key_id": "your_actual_api_key_id",
         "api_key_secret": "your_actual_api_key_secret"
     }
     ```

     Then, configure the client:

     Python

     ```python
     from jua import JuaClient

     settings = {
         "auth": {
             "api_key_path": "/path/to/your/my_jua_key.json"
         }
     }
     client = JuaClient(settings=settings)
     ```

     Ensure the path to the JSON file is correct and the file is appropriately secured.

***

#### 4. Using a Global `api-key.json` File

This method allows for a system-wide default API key. It should be used with caution, as it makes the key available to any Jua SDK usage by that user on the system.

1. **Obtain your Credentials:** Get your `API Key ID` and `API Key Secret` from the Jua dashboard.
2. **Create the JSON file:** Create a file named `api-key.json` with the following content:

   JSON

   ```jsonp
   {
       "api_key_id": "your_actual_api_key_id",
       "api_key_secret": "your_actual_api_key_secret"
   }
   ```
3. **Place the file in the correct directory:** Save or copy this file to `~/.jua/default/api-key.json`.
   * `~` refers to your user's home directory (e.g., `/home/username` on Linux, `/Users/username` on macOS).
   * You may need to create the `.jua` and `default` directories if they don't exist:

     ```bash
     mkdir -p ~/.jua/default
     ```

**Security Note:** Ensure that file permissions for `~/.jua/default/api-key.json` are restrictive (e.g., readable only by the user) to protect your credentials.

***

### Order of Precedence

If multiple authentication methods are configured, the Jua SDK typically follows this order of precedence (from highest to lowest):

1. **Programmatic Configuration:** Credentials passed directly to the `JuaClient` constructor (either as direct parameters/settings object or via `api_key_path`).
2. **Environment Variables:** `JUA_API_KEY_ID` and `JUA_API_KEY_SECRET`
3. **Jua CLI Configuration:** (Once available) Credentials configured via `jua auth login`.
4. **Global `api-key.json` File:** Credentials from `~/.jua/default/api-key.json`.

The first valid set of credentials found will be used.

### Security Best Practices

* **Never commit API keys or secrets directly into your version control system (e.g., Git).** Use `.gitignore` for files like `.env` or specific key files.
* **Use the principle of least privilege:** Generate API keys with only the necessary permissions for the task at hand if your dashboard supports scoped keys.
* **Store secrets securely:** For production environments, consider using dedicated secret management services (e.g., HashiCorp Vault, AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault) and load them into environment variables or directly into your application at runtime.
* **Rotate your API keys regularly** as a security precaution.

***

For further details, advanced configuration options, or troubleshooting, please refer to the **Technical Documentation** or contact Jua support.