Introduction
When working with OCI Generative AI, one of the most common questions engineers struggle with is:
"How exactly should I authenticate when calling GenAI services?"
Should you use:
Dynamic Groups with Instance or Resource Principals?
The global OCI tenancy API key?
Or the newly launched API Keys for OCI Generative AI?
Oracle’s documentation covers each option individually, but the practical differences — especially when agents are involved — are often unclear. This confusion frequently leads to authorization errors like “Authorization failed or requested resource not found”, even when IAM policies appear correct.
In this article, we’ll break down when to use each authentication method, what they can and cannot do, and how to choose the right one for your OCI Generative AI workload.
The Three Authentication Options in OCI Generative AI
1. Dynamic Groups with Instance / Resource Principals
This is the recommended enterprise approach for OCI-native workloads.
How it works
Your OCI resource (Compute VM, OKE Pod, Function, etc.) is added to a Dynamic Group
IAM policies grant that dynamic group access to Generative AI services
Authentication happens automatically via Instance Principal or Resource Principal
Example policy:
What this is used for
OCI Compute → Generative AI
OCI Functions → Generative AI
OKE workloads → Generative AI
Supported GenAI features
Model inference
Embeddings
GenAI Agent Runtime (agents, RAG, tools)
Object Storage integration
Enterprise IAM governance
This is mandatory when calling:
2. Global OCI Tenancy API Keys
These are the classic OCI user API keys.
How they work
API key is generated for an IAM user
Requests are signed using OCI’s request signing mechanism
Typically used from laptops, CI/CD, or external systems
Downsides
Long-lived credentials
Manual key rotation
Not ideal for workloads running inside OCI
Supported GenAI features
Model inference
Limited agent support
Not recommended for production agents
Oracle generally discourages this approach for GenAI workloads running on OCI resources.
3. Newly Launched OCI Generative AI API Keys
In early 2025, Oracle introduced service-specific API keys for Generative AI:
🔗 Official announcement:
https://docs.oracle.com/en-us/iaas/releasenotes/generative-ai/api-keys.htm
These are not OCI tenancy API keys.
What makes them different
Scoped only to OCI Generative AI
Simple Bearer-token authentication
Similar in concept to OpenAI or Anthropic API keys
No OCI request signing required
Supported endpoints
Supported GenAI features
Chat completion
Text generation
Embeddings
Critical limitation
GenAI Agent Runtime is NOT supported
API keys cannot authenticate against:
This means:
No agents
No RAG
No tools
No memory
No OCI service integrations
Oracle Generative AI has two distinct service planes:
| Plane | Purpose | Auth supported |
|---|---|---|
| Inference Plane | Direct model calls | API Keys, IAM |
| Agent Runtime Plane | Agents, tools, RAG | IAM only |
The new API keys work only for inference, while agents are treated as first-class OCI resources, governed by IAM.
Which One Should You Use?
Use Dynamic Groups + Instance Principal if:
You are calling GenAI Agents
Your workload runs inside OCI
You need RAG, tools, Object Storage access
You want enterprise-grade security
Use GenAI API Keys if:
You only need model inference
You are calling from outside OCI
You want quick experimentation
You do NOT need agents
Avoid Global Tenancy API Keys when possible
They still work, but they are rarely the best option for modern GenAI workloads. These API keys are stored in your resources such as VM and hence poses security risks.
Final Thoughts
OCI Generative AI gives multiple authentication choices — but they are not interchangeable.
The new GenAI API keys simplify access to hosted models, while dynamic groups and instance principals remain the only supported path for GenAI Agents.
Understanding this distinction upfront can save hours of debugging IAM policies and mysterious 404 authorization errors
No comments:
Post a Comment