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

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.

  • Each secret provides the same level of access and is tied to the same API key. You can use either secret interchangeably in applications.
  • You can name each secret and set an expiration date for zero-downtime rotation.
  • When your application calls an OCI Generative AI model endpoint, include either secret in the Authorization header.

When to Use This 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 the following SDKs:

Important

These API keys are compatible only with Supported OpenAI SDKs.

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.

Limits

Tokens per minute (TPM)
By default you get 100 API keys per tenancy. To request a limit increase, use the following limit name, api-key-count.

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.