Oracle Cloud Infrastructure Documentation

API Keys

OCI Generative AI API keys are secure credential tokens used to authenticate callers and authorize access to large language models hosted by the OCI Generative AI service.

About the API Key

An OCI Generative AI API key is a secret token (a string) specific to the OCI Generative AI service. You can generate an API key and use it to access the large language models hosted by the service.

This API key is different from an OCI IAM API key, which uses a public/private key pair to provide general OCI tenancy access.

How the API Key Works

Each OCI Generative AI API key includes two separate secrets, such as key-one and key-two. Both secrets are unique strings.

  • You create the API key through the Generative AI service and name and set expiration dates for its two secrets.
  • Each secret provides the same level of access and is tied to the same API key. You can use either secret interchangeably in applications.
  • When your application calls an OCI Generative AI model endpoint, include either secret in the Authorization header.
Important

The API key must be in the same region as the model that you want to use it with.

How to Use the API Key

You can generate OCI Generative AI API keys and use them to access large language model endpoints hosted by the Generative AI service using REST API or the native openai SDK. Here are the steps to use the API keys.

  1. In OCI Generative AI, Create an API key in a supported region for the model that you want to use.
  2. In OCI IAM, Add API Key Permissions.
  3. Use this key when you call a supported model in a supported region through on of the following options:

Supported Models

Models for Chat Completions API
Models for Responses API
Important

External Calls

The xAI Grok models are hosted in an OCI data center, in a tenancy provisioned for xAI. The xAI Grok models, which can be accessed through the OCI Generative AI service, are managed by xAI.

Using API Keys with REST API

You can use the API keys in headers of REST API and curl. Here are the endpoints that you can use for the REST API.

Supported Endpoints

Chat Completions
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/chat/completions
Responses
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/responses

Example using curl:

curl 
--location 'https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1/chat/completions' \
--header 'Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
"model": "xai.grok-4",
"messages": [
    {
    "role": "user",
    "content": "What's the capital of France?"
    }
]
}'

Using API Keys with OpenAI SDKs

You can use the API keys with OpenAI SDK. Here are the endpoints that you can use for the OpenAI SDK.

Supported Endpoints

Specify the base_url as 
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1
Chat Completions
Use this method: client.chat.completions.create
Responses
Use this method: client.responses.create
Example
from openai import OpenAI
import os

API_KEY=os.getenv("OPENAI_API_KEY")

print(API_KEY)

client = OpenAI(
    api_key=API_KEY,
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1"
)

# Responses API
response = client.responses.create(
    model="openai.gpt-oss-120b",
    # model="xai.grok-3",
    # meta models are not supported with the Responses API
    input="Write a one-sentence bedtime story about a unicorn."
)
print(response)

# Completion API
response = client.chat.completions.create(
    # model="openai.gpt-oss-120b",
    # model="meta.llama-3.3-70b-instruct",
    model="xai.grok-3",
    messages=[{
        "role": "user", 
        "content": "Write a one-sentence bedtime story about a unicorn."
        }
    ]
)
print(response)
Reference
Oracle GitHub repository

Supported Regions

Regions

For OpenAI SDKs, the supported OCI regions to use with API keys are limited to:

  • Germany Central (Frankfurt)
  • India South (Hyderabad)
  • Japan Central (Osaka)
  • US East (Ashburn)
  • US Midwest (Chicago)
  • US West (Phoenix)

To confirm a model’s usable regions for the OCI OpenAI package perform the following tasks.

  1. Open the model’s card in the Generative AI documentation:
  2. Note the regions listed for that model.
  3. Select a region for the model that appears in both the model’s available regions AND the preceding six OCI OpenAI regions.
  4. Verify whether the model is available in the mode that you need (on-demand or dedicated).

    For access to models in the dedicated mode, both public and private endpoints are supported.

Rotating or Replacing a Key

To rotate an OCI Generative AI API key, you can change its state in the OCI Console or by using the SetApiKeyState operation with the API. Here are the steps:

  1. Activate the standby secret. Activate the unused secret (for example, key-two) and update your applications to use it.
  2. Verify fail-over. Confirm that requests authenticate with the newly activated secret and that workloads continue without interruption.
  3. Revoke or deactivate the first secret.
    • If you suspect a leak or it's time to retire the first secret, revoke it. After the change propagates, the requests using the revoked secret are rejected. Revoking a secret permanently disables it, and the action is irreversible.
    • If you plan to reuse the first secret, deactivate it. After the change propagates, the requests using the deactivated secret are rejected until you reactivate it.
    Tip

    Deactivate a secret for short-term suspension or investigation. Revoke a secret if it has been compromised or if you need to permanently retire it.

For steps on how to perform these tasks, see Managing API Keys.

Important

Copy new or regenerated secrets immediately and store them securely. They appear only once.

Best Practices

Always store OCI Generative AI API key secrets in an approved secrets manager. Never commit them to source control or embed them in client-side code.

  • Use the two-secret setup for smooth, zero-downtime rotation, and set expirations to regularly refresh keys.
  • Limit access to keys using compartments and least-privilege policies.
  • Monitor usage, set up alerts, and rotate keys immediately if you detect suspicious activity.

Examples on GitHub

For a hands-on experience, see examples in the Oracle GitHub repository.