API authentication
Use the URL and credential supplied by Connect, and distinguish application access from explicit endpoint and control-plane requests.
Start in your instance's Connect panel. Copy its database URL and the credential offered for that deployment.
- Copy the connectionTake the database URL and credential from Connect.
- Configure your applicationStore the connection values in your server environment.
- Check SQL accessRun a small read query with the bearer credential.
Application SQL
Use OC_URL exactly as supplied by Connect. It is an opaque database address: do not build it from an instance name or add or remove tenant segments.
Send SQL to $OC_URL/sql with the bearer credential in OC_TOKEN. Bind values through params instead of inserting them into the SQL string.
export OC_URL="<database URL from Connect>"
export OC_TOKEN="<credential from Connect>"
curl --include --request POST "$OC_URL/sql" \
--header "Authorization: Bearer $OC_TOKEN" \
--header "Content-Type: application/json" \
--data '{"sql":"SELECT $1 AS value","params":[1]}'The query should return one row with value equal to 1; it creates no table and changes no data. A successful response checks this SQL connection, not permission to every table.
Access tokens are supported on dedicated, non-raft, non-sharded configurations that report token support. Other configurations still require the instance credential shown in Connect. Check the reported capability; there has been no blanket cutoff of instance keys.
Explicit database endpoint requests
The endpoint reference retains paths such as /v1/tenants/{tenant}/schemas. Its examples use these separate values:
| Variable | Meaning |
|---|---|
OC_BASE_URL | Database origin for the explicit endpoint contract, without a trailing slash. |
OC_TENANT | Tenant ID for that endpoint. |
OC_TOKEN | Database bearer credential accepted by that deployment. |
Do not derive these values by trimming or editing OC_URL. Use the values provided for the explicit endpoint contract.
Example: list schemas through the explicit endpoint
export OC_BASE_URL="https://your-database-host"
export OC_TENANT="your-tenant"
export OC_TOKEN="<database-token>"
curl --include "$OC_BASE_URL/v1/tenants/$OC_TENANT/schemas" \
--header "Authorization: Bearer $OC_TOKEN"Database identity
Some deployment policies also require an acting database user and key. Send the pair together when required. OC_DB_USER and OC_DB_KEY below are example environment-variable names; obtain the values from your database administrator.
# Add both headers when your deployment requires database identity.
curl --include "$OC_BASE_URL/v1/tenants/$OC_TENANT/schemas" \
--header "Authorization: Bearer $OC_TOKEN" \
--header "x-oc-db-user: $OC_DB_USER" \
--header "x-oc-db-key: $OC_DB_KEY"See roles and permissions for database access controls.
Control-plane requests
Managed embeddings and project vector indexes use an organization API key on the control-plane origin. Call these routes from your server; cross-origin browser requests are not supported.
export OC_ORG_API_KEY="<organization-api-key>"
curl --include "https://api.originchain.ai/v1/embeddings/catalog" \
--header "Authorization: Bearer $OC_ORG_API_KEY"Credentials and permissions
Keep secrets in a server environment or secret manager. Personal-token access is limited by the owner's current role; organization tokens use their explicit grants and database-user binding.
Token revocation and propagation to database engines are separate. A successful control-plane deletion is not proof that every database engine has already rejected that credential.
PostgreSQL clients use a separate database username and password over TLS. They do not use OC_TOKEN as the password; the offered login capability remains read-only. See PostgreSQL connection setup.