Oracle Cloud Infrastructure Documentation

Generative AI IAM-Based Authentication

You can reach the OpenAI-Compatible endpoint using the following two authentication methods:

Use API keys for testing and early development. Use IAM-based authentication for production workloads and OCI-managed environments. This topic shows how to set up OCI IAM authentication.

OCI IAM Authentication

The OCI Responses API fully supports OCI IAM authentication. This section shows how to use IAM-based authentication instead of API keys.

When to Use IAM Authentication

Consider using IAM authentication when:

mc

  • Running applications in OCI services (for example, Functions or OKE)
  • Avoiding long-lived credentials such as API keys
  • Enforcing fine-grained access control through IAM policies

Install the OCI IAM Auth Library

Install the oci-genai-auth library, which provides helper utilities for integrating OCI IAM authentication with the OpenAI SDK:

pip install oci-genai-auth

This library includes the following authentication helpers:

  • OciSessionAuth (for local development)
  • OciUserPrincipalAuth
  • OciInstancePrincipalAuth
  • OciResourcePrincipalAuth (for OCI-managed environments)

Resources

Configure the OpenAI Client

When using IAM authentication, initialize the OpenAI client with a custom HTTP client and authentication handler. The api_key value is "not used" in this case.

Example: Local Development (OciSessionAuth)

Use this approach when running code locally (for example, on a laptop using an OCI CLI profile):

from openai import OpenAI
from oci_openai import OciSessionAuth
import httpx

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",  # update region if needed
    api_key="not-used",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",  # project OCID created earlier
    http_client=httpx.Client(auth=OciSessionAuth(profile_name="DEFAULT"))  # update profile if needed
)

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    input="Write a one-sentence explanation of what a database is."
)

print(response.output_text)

Example: OCI Managed Environments (OciResourcePrincipalAuth)

Use this approach when running in OCI services such as OCI Functions or OCI Container Engine for Kubernetes (OKE):

from openai import OpenAI
from oci_openai import OciResourcePrincipalAuth
import httpx

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",  # update region if needed
    api_key="not-used",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",  # project OCID created earlier
    http_client=httpx.Client(auth=OciResourcePrincipalAuth()),
)

Using OCI IAM authentication allows the application to securely access OCI Generative AI without managing API keys, while aligning with standard OCI security practices.