Connecting Using Basic Authentication

Prerequisites

Before configuring authentication, ensure that the following prerequisites are met:

Obtain the exact HTTPS URL of the Cloud EPM environment and an Oracle account that can access it.
Confirm with your administrator that the account can use password-based REST authentication. Accounts configured to require multifactor authentication (MFA) for Basic REST authentication cannot use this procedure.
Ensure that the account has the roles required for the requested operations. A successful sign-in does not grant additional administrative privileges or access to every application.
Configure the AI agent to run the package. Core and shared Auth require Python 3.10 or later. Planning and Strategic Modeling also require Node.js. Preserve the complete package folder structure.
Ensure that the agent’s execution environment can reach the Cloud EPM environment through the permitted network route and has writable private storage for session information.

Note:

A cloud-hosted agent cannot access a file solely from a path on your local computer. Upload the required files using the method supported by your AI agent.

Creating a Private Configuration File

To create a private configuration file:

Create a plain-text file and copy the following configuration into it:
```
EPM Environment URL: <exact HTTPS EPM environment URL1>
EPM Environment Name: <Symbolic short name to refer to this environment, for example, EPM Test>
Username: <your EPM username>
Password: <your EPM password>
```
- Keep the four labels exactly as shown and replace each placeholder with the appropriate value.
- Preserve the username format supplied by your administrator.
Save the file in a private location and restrict access:
- On Windows, limit access to your user account.
- On macOS or Linux, ensure that the execution user owns the file and that group and other users have no access.

Note:

Do not enter your password in chat or copy the configuration file to a shared documentation folder or source repository. The Auth skill reads the configuration file privately without displaying its contents in the conversation.

Selecting the Configuration File and Requesting a Connection

To prepare a connection:

Select or upload the configuration file in your AI agent.
For a local desktop agent, you can provide the absolute path to a private configuration file that the execution environment can access. For a browser-based agent, upload the file.
Enter a prompt such as the following, replacing EPM Test with the environment name specified in your configuration file:
```
Use the selected configuration file for EPM Test.
Then get the daily maintenance start time and time zone.
```
If the agent cannot use Basic authentication credentials from a file, run the bootstrap script included with EPM AI Skills and provide the resulting environment registry path to the agent.
1. Open a command prompt and run the following command, replacing the example paths with the locations of your script and configuration file:
```
py -3 "C:\Users\John Smith\.claude\skills\EPM_Agent_Skills\Auth\scripts\epm_auth.py" bootstrap --basic-config-file "C:\Users\John Smith\epm-private\epm1.txt"
```
  In this example,
```
C:\Users\John
      Smith\epm-private\epm1.txt
```
  is the configuration file created in the previous step.
2. Locate the environment_registry value in the command output. For example:
```
environment_registry": "C:\Users\John Smith\AppData\Local\OracleEPM\oracle-epm-session-z0aehjqx\environments.json
```
3. Provide the returned registry path to the agent and identify the environment to use. For example:
```
Use the environment registry at
C:\Users\John Smith\AppData\Local\OracleEPM\oracle-epm-session-z0aehjqx\environments.json
for EPM Test. Then get the daily maintenance start time and time zone.
```
  Repeat for each environment that you want to use, using the registry path returned for that environment.

Validating the Connection

The Auth skill validates the selected configuration file and prepares a private session locally. This step does not send a request to Cloud EPM or verify access to the environment.

The requested supported live operation then uses the session. A successful response confirms access for that operation. Other operations may require different roles or may not be available for the selected business process or environment.

Reusing an Environment Session

After setup, submit follow-up requests such as List the cubes in Vision in EPM Test or Get the dimensions for Plan3.

The agent reuses an available session for the same environment and identity. You do not need to provide your password again or create a new session for each read request.

Connecting to Multiple Environments

Add a complete four-line configuration block for each environment to the same file. Specify a unique, nonempty environment name and include the URL and credentials in each block, even when the same account is used.

The following example uses placeholders:

EPM Environment URL: <test environment HTTPS URL>
EPM Environment Name: EPM Test
Username: <test username>
Password: <test password>

EPM Environment URL: <production environment HTTPS URL>
EPM Environment Name: EPM Production
Username: <production username>
Password: <production password>

To prepare sessions for both environments, enter:

Prepare Basic Auth sessions for both environments in my selected file.
Use EPM Test for the next request.

To switch environments, specify the environment name:

Get the maintenance window for EPM Production.

The Auth skill creates a separate session for each selected environment.. The agent uses the requested environment name rather than automatically selecting the first configuration block. If the target environment is unclear, the agent asks you to select one.

Updating Credentials and Resolving Failures

If your password changes, update your private configuration file and ask the agent to prepare a new basic authentication session for the named environment.

If a live request fails, the agent reports the available error with sensitive information removed and stops. It does not automatically try different credentials, another product, or another connection method.

A Domain Name System (DNS) or local runtime error does not establish that credentials were rejected. An HTTP 401 or 403 response alone does not identify the specific credential or role issue. If needed, ask your administrator to verify the environment URL, username, eligibility for password-based REST authentication, and required roles.

You can explicitly request one retry of a failed read. If basic authentication credentials are rejected, the Auth skill follows its recovery procedure, and the agent makes the requested attempt using the selected configuration file and target environment.

Note:

If the outcome of a change is uncertain, verify the actual state in Cloud EPM before submitting the change again.

EPM Agent Skills and Prompt Examples

Review skill descriptions, supported business processes, and example prompts for each skill and supporting workflow in EPM Agent Skills in Features with AI .