Install AI Agent Skills  View Python SDK  View Notebook  Open in Colab

Connect to Oracle AI Database with Python: Authentication and Configuration

Configure the Oracle VecDB Python SDK to connect to an Oracle AI Database REST endpoint, authenticate as a vector user, and verify the connection. The Python client sends requests to the SDK REST endpoint. ORDS (Oracle REST Data Services) exposes the database operations that the client calls over HTTPS. Choose username and password authentication for a quick start, or OAuth 2.0 client-credentials authentication when your application should use a bearer token.

To run this guide in a notebook, select Open in Colab above.

The notebook follows the same authentication, client configuration, connection verification, and TLS/proxy/retry flow as this page.

When you finish

You will have a configured OracleVecDB client, a verified authentication path, and the endpoint details needed to make Python SDK requests. If you use OAuth 2.0, you will also have a repeatable way to request a new access token when the current token expires.

Choose an authentication method

Authentication method Use when Instructions
Username and password You are following the quickstart or developing locally. Configure basic authentication
OAuth 2.0 bearer token Your application uses service-to-service authentication or should not send the <VECTOR_USER> password. Configure OAuth 2.0 bearer-token authentication

The quickstart uses username and password authentication. You can switch to OAuth 2.0 bearer-token authentication without changing the SDK REST endpoint.

What you need

Before you begin, make sure that you have:

The database setup pages explain how to create the user, load the all_MiniLM_L12_v2 model, and obtain the REST endpoint:

Configure basic authentication

Use the SDK REST endpoint with the <VECTOR_USER> credentials created during database setup. The SDK endpoint is different from the Vector Database Console URL: the Console URL opens a browser interface, while the SDK REST endpoint is the API base URL passed to Configuration.

from oracle_vecdb import Configuration, OracleVecDB

config = Configuration(
    rest_url="https://<host>:<port>/ords/<vector_user>/_/db-api/stable/vecdb/",
    username="<VECTOR_USER>",
    password="<VECTOR_USER_PASSWORD>",
)

vecdb = OracleVecDB(config)

Use the REST URL mapping in the /ords/<vector_user>/ part of the endpoint. Update <host>, <port>, and <vector_user> with the values from your deployment setup page. Keep the user name and password out of source control.

Warning: Use the lowercase REST URL mapping in the /ords/<vector_user>/ segment. The mapping is separate from the uppercase <VECTOR_USER> database user name used for authentication. For example, a database user named VECTOR_USER uses /ords/vector_user/ in the endpoint.

Configure OAuth 2.0 bearer-token authentication

Use OAuth 2.0 when your application should authenticate with a client ID and secret instead of sending the <VECTOR_USER> password. This is service-to-service authentication: your application exchanges the client ID and secret for a short-lived access token, then sends the token with SDK requests. The OAuth client belongs to the vector user and must have the VecDB role.

1. Create an OAuth client in Database Actions

Sign in to Database Actions as <VECTOR_USER>, then complete the following steps:

  1. Select Development, then select REST.
  2. Open Clients and select Create OAuth Client.
  3. On the Client Definition tab, set Grant type to CLIENT_CRED.
  4. Enter a name and description for the client. You can also provide a support email and, optionally, a support URI.
  5. On the Roles tab, add oracle.dbtools.auth.roles.builtin.VecDB to the client.
  6. Select Create.

Save the client ID and client secret when they are displayed. The client secret is shown only when the client is created. If you lose it, rotate the secret and update your application.

Caution: Treat the client secret like a password. Do not commit it to source control, include it in client-side code, or write it to application logs.

For the general Database Actions OAuth client administration procedure, see Configure an OAuth Client.

2. Request an access token

Use the client ID and client secret to request an access token from the OAuth token endpoint. Replace <host>, <port>, and <vector_user> with the values from your deployment setup page. Run this command in a terminal or shell. If you are using a Jupyter notebook, add %%bash as the first line of the cell so that the cell runs as Bash instead of Python. Do not save the client secret in a notebook or source file.

curl -i -k \
  --user "<CLIENT_ID>:<CLIENT_SECRET>" \
  --data "grant_type=client_credentials" \
  "https://<host>:<port>/ords/<vector_user>/oauth/token"

The example includes -k so it also works with the self-signed certificate generated by a local ADB-Free container. The option disables TLS certificate verification; use it only for local testing. For an endpoint with a trusted certificate, remove -k. For a local container, you can add the certificate to your host trust store by following Trust the local HTTPS certificate. The response contains an access token. Use the value of access_token in the Python client configuration. Access tokens expire, so request a new token with the same command when one expires. If the client secret is exposed, rotate it in Database Actions before requesting another token.

3. Configure the Python client

Pass the access token to Configuration:

from oracle_vecdb import Configuration, OracleVecDB

config = Configuration(
    rest_url="https://<host>:<port>/ords/<vector_user>/_/db-api/stable/vecdb/",
    access_token="<BEARER_TOKEN>",
)

vecdb = OracleVecDB(config)

The token endpoint and SDK REST endpoint use the same host, port, and REST URL mapping. The token endpoint ends with /oauth/token; the SDK endpoint ends with /_/db-api/stable/vecdb/.

4. Verify the connection

Call describe_vector_database() to confirm that the user can access the VecDB REST API:

summary = vecdb.describe_vector_database()
print(summary)

The response contains summary counts for the vector tables, vectors, and models in the <VECTOR_USER> schema. A successful response confirms that the endpoint and credentials are working.

For the method definition, see describe_vector_database.

Request a new access token after expiration

The client-credentials flow returns a short-lived access token and an expires_in value. When the access token expires, request a new one by repeating the client-credentials request with the same client ID and client secret.

Replace the expired bearer token with the new access_token value in subsequent SDK requests.

Configure TLS, a proxy, and retries

Use additional Configuration options when your environment requires custom certificate verification, an HTTP proxy, or retries:

config = Configuration(
    rest_url="https://<host>:<port>/ords/<vector_user>/_/db-api/stable/vecdb/",
    username="<VECTOR_USER>",
    password="<VECTOR_USER_PASSWORD>",
    ssl_ca_cert="/path/to/self-signed.crt",
    retries=3,
)

config.proxy = "http://proxy.example.com:8080"
vecdb = OracleVecDB(config)

For all configuration parameters, environment variables, attributes, and methods, see Configuration.

For a local ADB-Free container, set ssl_ca_cert to the host path of the self-signed.crt file copied from the running container. This lets the Python client verify ORDS while keeping TLS verification enabled. Trusting the certificate in a browser does not configure the Python SDK’s certificate bundle.

Troubleshoot the connection

Related sample

The Embedding & Ingest Patterns notebook loads connection settings, creates an OracleVecDB client, and reuses it across a complete workflow.

Next steps