Authenticate and manage access
Use the database URL and credential offered in Connect. Some deployments also require a database user and key so that user's permissions can be checked.
- Copy the connection credentialUse the complete address and token supplied in Connect.
- Set database permissionsUse the required database identity and only the grants it needs.
- Send credentials from your serverKeep tokens outside browser code and URLs.
- Test the access boundaryCheck a permitted request and a request that should be refused.
1. Create an instance token
Open Connect on the target instance in the console. Where access tokens are supported, use Your tokens or Organization tokens, depending on who owns the credential. Otherwise use the instance credential offered by Connect. Save a new secret when it is shown; it cannot be revealed later.
Personal instance tokens inherit the member's effective access. A read-only token cannot write, and choosing read/write cannot exceed the member's role or grants. Tokens are scoped to their instance and tenant; a valid token does not grant access to every database. Use the permission controls shown by your console rather than inferring access from a token prefix.
Choose the credential for the task:
- Instance token: authenticates requests to the database HTTP API.
- Organization API key: authenticates supported management operations.
- Database identity: identifies a database user and its permissions. HTTP uses that user's API key; a per-user SQL connection uses its login password.
These credentials are not interchangeable. See SQL client connections for database tools.
2. Make an authenticated request
For the current connection, copy the complete OC_URL and credential from Connect. Keep the URL's path unchanged. The connection example shows a first SQL request.
Using the explicit host-and-tenant API instead?
Use the values supplied for that API. Do not derive them by trimming or editing OC_URL.
# Use the explicit endpoint settings supplied for your deployment.
export OC_BASE_URL="https://YOUR_INSTANCE_HOST"
export OC_TENANT="YOUR_TENANT_ID"
# Set OC_BEARER from your secret manager; do not commit it to this file.
: "${OC_BEARER:?Set OC_BEARER first}"
curl --fail-with-body "$OC_BASE_URL/v1/tenants/$OC_TENANT/schemas" \
-H "Authorization: Bearer $OC_BEARER"This Bash example lists the schemas you are allowed to see. An empty list is valid for a new database. The tenant ID is not the instance ID.
Engine requests under /v1/tenants/… use Authorization: Bearer …. Public health and capability discovery routes are exceptions. Check the SDK directory before choosing a client version.
| Status | What to check |
|---|---|
401 | The token is missing, malformed, unknown, expired or revoked. Check the secret and the credential type. |
403 | The caller is authenticated but cannot perform this operation. Check tenant scope, read/write access, database grants and row policies. Creating a new token does not increase the member's permissions. |
404 | Check the host, route and object name. Some restricted resources are deliberately hidden; this status alone does not prove that an instance was deleted. |
Database permissions over HTTP
Bearer authentication and database-user authorization are separate checks. When database identity is required, include X-OC-DB-User and X-OC-DB-Key as well as the bearer token. The key is the database user’s API key, not a SQL login password or an organization API key. Obtain the identity from your administrator and load its key from a secret manager.
curl --fail-with-body "$OC_BASE_URL/v1/tenants/$OC_TENANT/schemas" \
-H "Authorization: Bearer $OC_BEARER" \
-H "X-OC-DB-User: $OC_DB_USER" \
-H "X-OC-DB-Key: $OC_DB_KEY"Identity requirements depend on the instance configuration. A bearer-only request must not be used as proof that database-user row policies or masks were applied. If identity is required and missing, fix the credentials instead of weakening the requirement. Confirm both an allowed operation and a denied operation with the intended application identity.
Use the authentication options documented for your installed client version. Source code for a newer SDK is not proof that its package has been published. The HTTP example above shows the identity headers directly. Keep database secrets on your server.
3. Store credentials safely
Load tokens from a secret manager or server environment. Keep them out of browser bundles, mobile application packages, URLs, screenshots and logs. Use the least privilege required, and an expiry where your token-creation workflow offers it. A database identity or token may have less than full access, but its secret still lets another person act with that access.
4. Rotate and confirm
- Create a replacement token with the required access and save it securely.
- Update your application's secret and reload its clients or restart the application.
- Run a small request using the replacement and confirm the expected result.
- Revoke the old token. Check the console's confirmation state; if propagation is pending, use the offered check or retry action.
- Confirm the old credential is refused. A successful management request alone is not proof that every running engine has applied the change.
Removing a member revokes their personal instance tokens across the organization's instances. Review the Team page for any confirmations still pending. Shared organization API keys require a separate review.
5. If a token leaks
Revoke it immediately, check the propagation status, replace it in affected applications and review activity. Remove exposed copies from repositories and logs, including history where appropriate. Contact security@originchaindb.com with the instance, time and request IDs; never send the secret.