Authentication

Corva's Platform API and Data API accept two authorization methods:

Method	Header	Best for
API key	Authorization: API YOUR_API_KEY	Long-running services, scheduled exports, and integrations with intentionally scoped access.
Bearer token	Authorization: Bearer YOUR_JWT	User-scoped API access and API-only customers authenticating with Corva credentials.

Which should I choose?

Use an API key when your integration can be assigned a stable, least-privilege identity. Use a Bearer token when the request must run with a Corva user's permissions or when API access is obtained by signing in through the API.

API key authentication

The API prefix and the space before the key are required.

Authorization: API YOUR_API_KEY

Create an API key

API-key creation is not enabled by default

Most customer users do not have permission to create or approve API keys. If API Keys is unavailable in Control Center, contact your Corva representative to request a key. If you do not need a long-lived integration identity, use Bearer token authentication with your Corva credentials instead.

1. Open Control Center in your Corva account.
2. Select API Keys.
3. Select New API Key.
4. Choose the company, owner, and minimum permissions required by the integration.
5. Give the key a name that identifies its purpose, such as power-bi-drilling-read.
6. Copy the key when it is displayed and store it securely.

These steps apply only after Corva has granted the required API-key management permission.

API-key expiration

Standard customer API keys do not have an automatic expiration time by default. They remain valid until they are deactivated, revoked, or replaced. Corva can issue a time-limited key for a specific workflow; when a key has an assigned expiration, requests stop authenticating after that time.

Because standard keys are long-lived, rotate them according to your organization's security policy and revoke them as soon as an integration is retired or a key may have been exposed.

Permission levels

Permission	Use
Read	Retrieve platform entities and dataset records. Recommended for analytics and exports.
Read/write	Read and modify permitted resources. Use only when the integration must write data.
Admin	Broad administrative access. Avoid for customer integrations unless explicitly required.

The key is also scoped by its associated company, owner, and resource permissions. A valid key can still receive 403 Forbidden when it does not have access to the requested resource.

Bearer token authentication

Send the jwt returned by the token endpoint as a Bearer token:

Authorization: Bearer YOUR_JWT

The token uses the permissions of the Corva user who authenticated. User group permissions, company access, account state, security policies, and IP restrictions can therefore affect the resources available to the token.

Generate a Bearer token with Corva credentials

API-only customers can exchange Corva credentials for API access without using Dev Center or Control Center.

POSThttps://api.corva.ai/v1/user_token

Request field	Type	Required	Description
auth.email	string	Yes	Corva account email.
auth.password	string	Yes	Corva account password.

curl 'https://api.corva.ai/v1/user_token' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "auth": {
      "email": "customer@example.com",
      "password": "YOUR_CORVA_PASSWORD"
    }
  }'

import os
import requests

response = requests.post(
    "https://api.corva.ai/v1/user_token",
    json={
        "auth": {
            "email": os.environ["CORVA_EMAIL"],
            "password": os.environ["CORVA_PASSWORD"],
        }
    },
    timeout=30,
)
response.raise_for_status()
credentials = response.json()

jwt = credentials["jwt"]
refresh_token = credentials["refresh_token"]

A successful response has this shape. Token values are shortened placeholders here.

{
  "jwt": "eyJ...access-token",
  "auth_key": "eyJ...access-token",
  "refresh_token": "eyJ...refresh-token",
  "user_id": 1042,
  "intercom_hash": "..."
}

Use the jwt value for API requests. auth_key currently contains the same access token and is retained for compatibility.

Token lifetime

Bearer access tokens expire after seven days by default. A company security policy can configure a different lifetime, so clients should use the token's exp claim rather than assuming seven days. Refresh tokens expire after six months and may become invalid earlier when the account or session is revoked.

Refresh a Bearer token

Exchange the refresh token at the same endpoint. The response contains a new jwt and a new refresh_token; replace both stored values.

curl 'https://api.corva.ai/v1/user_token' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "auth": {
      "refresh_token": "YOUR_REFRESH_TOKEN"
    }
  }'

response = requests.post(
    "https://api.corva.ai/v1/user_token",
    json={"auth": {"refresh_token": refresh_token}},
    timeout=30,
)
response.raise_for_status()
credentials = response.json()

jwt = credentials["jwt"]
refresh_token = credentials["refresh_token"]

If refresh returns 401, discard the stored tokens and authenticate again. Do not repeatedly submit a failed refresh token.

Store credentials and tokens safely

Treat every credential as a secret

Never put a password, API key, JWT, or refresh token in documentation, source control, screenshots, notebooks, client-side bundles, URLs, or shared chat messages.

For local scripts, read secrets from environment variables:

export CORVA_API_KEY='YOUR_API_KEY'
# Or, for user authentication:
export CORVA_EMAIL='customer@example.com'
export CORVA_PASSWORD='YOUR_CORVA_PASSWORD'

For deployed integrations, use the secret-management system provided by your hosting platform. Avoid persisting the Corva password after obtaining tokens. Never generate tokens from a browser or other public client where the password or refresh token can be exposed.

Verify authentication

Use either supported header with the same request:

# API key
curl --get 'https://api.corva.ai/v2/wells' \
  --header "Authorization: API ${CORVA_API_KEY}" \
  --data-urlencode 'per_page=1' \
  --data-urlencode 'fields[]=well.name'

# Bearer token
curl --get 'https://api.corva.ai/v2/wells' \
  --header "Authorization: Bearer ${CORVA_JWT}" \
  --data-urlencode 'per_page=1' \
  --data-urlencode 'fields[]=well.name'

Result	Meaning
200 OK	Authentication is valid and the request is allowed.
401 Unauthorized	Authentication is missing, malformed, expired, or invalid; the user may also need to satisfy an account security requirement.
403 Forbidden	Authentication is valid but does not grant access to the requested resource.

Rotate or revoke access

For an API key, create and verify a replacement before terminating the old key in Control Center. For Bearer access, replace refreshed tokens atomically and remove all tokens when the integration is disconnected. If any secret may have been exposed, revoke it immediately and contact your Corva administrator when user sessions also need to be terminated.