oci-genai-auth 1.0.0

OCI authentication and authorization utilities for Generative AI SDKs

oci-genai-auth

The OCI GenAI Auth Python library provides OCI request-signing helpers for the OpenAI-compatible REST APIs hosted by OCI Generative AI.

Table of Contents

• Installation
• Using OCI IAM Auth
• Using API Key Auth
• Using AgentHub APIs
• Using Partner APIs (passthrough)
• Running the Examples
• Contributing
• Security
• License

Installation

pip install oci-genai-auth

oci-genai-auth is designed to work together with the official OpenAI SDK.

Using OCI IAM Auth

Use OCI IAM auth when you want to sign requests with your OCI profile (session/user/resource/instance principal). Recommended if you are building OCI-native production workloads.

import httpx
from openai import OpenAI
from oci_genai_auth import OciSessionAuth

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    api_key="not-used",
    http_client=httpx.Client(auth=OciSessionAuth(profile_name="DEFAULT")),
)

Using API Key Auth

Use OCI Generative AI API Keys if you want a long-lived API key style auth. Recommended if you are migrating from other OpenAI-compatible API providers.

To create the OCI Generative AI API Keys, follow this guide.

You don't need to install oci-genai-auth if you use API key auth.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    api_key=os.getenv("OCI_GENAI_API_KEY"),
)

Using AgentHub APIs

OCI AgentHub provides a unified API for interacting with models and agentic capabilities.

• It is compatible with OpenAI's Responses API and the Open Responses Spec, enabling developers to build agents with OpenAI SDK, OpenAI Agents SDK, LangChain, LangGraph, AI SDK, CrewAI, and more.
• It offers a uniform interface, auth, billing to access multiple model providers including OpenAI, Gemini, xAI, and GPT-OSS models hosted in OCI and your Dedicated AI Cluster.
• It provides built-in agentic primitives such as agent loop, reasoning, short-term memory, long-term memory, web search, file search, image generation, code execution, and more.

In addition to the compatible endpoint to Responses API, AgentHub also offers compatible endpoints to Files API, Vector Stores API, and Containers API.

Explore examples to get started.

Note: OpenAI commercial models and image generation are only available to Oracle internal teams at this moment.

import httpx
from openai import OpenAI
from oci_genai_auth import OciSessionAuth

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    api_key="not-used",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.aaaaaaaaexample",
    http_client=httpx.Client(auth=OciSessionAuth(profile_name="DEFAULT")),
)

Using Partner APIs (passthrough)

OCI also offers Partner API which passes through your calls to partners such as OpenAI. We will support more partners in the future.

You can leverage Partner API when you want to use OpenAI's API and GPT models, but with OCI auth and billing.

Note: Currently Partner API is only available to Oracle internal teams. Only features that meet partner's Zero Data Retention are available through Partner API.

If you want multi-provider model access and features unavailable under partner's Zero Data Retention (such as File Search), use the AgentHub APIs above.

import httpx
from openai import OpenAI
from oci_genai_auth import OciSessionAuth

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1",
    api_key="not-used",
    default_headers={
        "opc-compartment-id": "ocid1.compartment.oc1..aaaaaaaaexample",
    },
    http_client=httpx.Client(auth=OciSessionAuth(profile_name="DEFAULT")),
)

Examples

Demo code and instructions on how to run them, for both agenthub and partner usecases can be found in examples folder.

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide

Security

Please consult the security guide for our responsible security vulnerability disclosure process

License

Copyright (c) 2026 Oracle and/or its affiliates.

Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.