Authentication — Access Tokens & API Keys

Learn how to authenticate with Deepvue APIs using client credentials for access tokens and API keys. Includes code examples and best practices.

Overview

Deepvue APIs require authentication for access. You can authenticate using an access token (obtained via client_id and client_secret) or using your client_secret as an API key header.

Authentication methods

Most Deepvue APIs use Bearer token authentication. You obtain a token by calling the Authorization endpoint with your credentials.

header

Authorizationstring

Required

Format: Bearer ACCESS_TOKEN

Authorization tokens remain valid for 24 hours from generation. After expiration, call the Authorize endpoint again to get a new token.

Getting your credentials

Visit the Deepvue Dashboard and sign in to your account.

Navigate to Credentials

Go to the credentials tab to find your client_id and client_secret.

Generate an access token

Call the Authorize endpoint with your credentials to get an access token.

Generating an access token

Use your client_id and client_secret to obtain an access token.

curl -X POST 'https://production.deepvue.tech/v1/authorize' \
  -F 'client_id=YOUR_CLIENT_ID' \
  -F 'client_secret=YOUR_CLIENT_SECRET'

import requests

response = requests.post(
    'https://production.deepvue.tech/v1/authorize',
    data={
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET'
    }
)
token = response.json()['access_token']

const formData = new FormData();
formData.append('client_id', 'YOUR_CLIENT_ID');
formData.append('client_secret', 'YOUR_CLIENT_SECRET');

const response = await fetch('https://production.deepvue.tech/v1/authorize', {
  method: 'POST',
  body: formData
});
const { access_token } = await response.json();

Successful response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expiry": "2026-03-08T00:00:00Z"
}

Making authenticated requests

Include the access token in the Authorization header for all subsequent API calls.

curl -X GET 'https://production.deepvue.tech/v1/verification/panbasic?pan_number=AAAPT0002F' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-api-key: YOUR_CLIENT_SECRET'

import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'x-api-key': 'YOUR_CLIENT_SECRET'
}
response = requests.get(
    'https://production.deepvue.tech/v1/verification/panbasic',
    params={'pan_number': 'AAAPT0002F'},
    headers=headers
)
print(response.json())

const response = await fetch(
  'https://production.deepvue.tech/v1/verification/panbasic?pan_number=AAAPT0002F',
  {
    headers: {
      'Authorization': `Bearer ${access_token}`,
      'x-api-key': 'YOUR_CLIENT_SECRET'
    }
  }
);
const data = await response.json();

Identifying your caller

Send the optional X-Deepvue-Origin header to label the product, service, or platform that makes each request. Deepvue shows the value in the Caller column of Transaction logs and in dashboard analytics, so you can tell your production app, staging environment, and test tools apart.

header

X-Deepvue-Originstring

A short label for your calling system, for example acme-web or loan-onboarding.

Use lowercase letters, digits, and hyphens only
Start with a letter or digit
Use at most 32 characters

The value must match ^[a-z0-9][a-z0-9-]{0,31}$.

curl -X GET 'https://production.deepvue.tech/v1/verification/panbasic?pan_number=AAAPT0002F' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-api-key: YOUR_CLIENT_SECRET' \
  -H 'X-Deepvue-Origin: acme-web'

import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'x-api-key': 'YOUR_CLIENT_SECRET',
    'X-Deepvue-Origin': 'acme-web'
}
response = requests.get(
    'https://production.deepvue.tech/v1/verification/panbasic',
    params={'pan_number': 'AAAPT0002F'},
    headers=headers
)
print(response.json())

const response = await fetch(
  'https://production.deepvue.tech/v1/verification/panbasic?pan_number=AAAPT0002F',
  {
    headers: {
      'Authorization': `Bearer ${access_token}`,
      'x-api-key': 'YOUR_CLIENT_SECRET',
      'X-Deepvue-Origin': 'acme-web'
    }
  }
);
const data = await response.json();

Value	Valid	Reason
`acme-web`	Yes	Lowercase letters and a hyphen
`loan-onboarding-2`	Yes	Digits are allowed
`postman web`	No	Contains a space
`Acme-Web`	No	Contains uppercase letters
`-acme-web`	No	Starts with a hyphen

Deepvue validates the header on every endpoint, including /v1/authorize. A value that does not match the pattern fails the whole request with a 400 and the sub-code INVALID_ORIGIN_METADATA. See Error codes.

Security best practices

All API requests must use HTTPS. Unencrypted HTTP calls will fail.

Restrict access to API credentials to only the personnel who need them
Do not store keys in version control systems
Use environment variables or secrets management tools for secure storage
Never expose credentials in client-side applications such as mobile apps or frontend code
Rotate credentials periodically and monitor usage through the dashboard

Common authentication errors

Status Code	Error	Solution
`401`	`Incorrect client_id or client_secret`	Verify your credentials from the dashboard
`401`	`Not authenticated`	Include a valid Bearer token in the Authorization header
`403`	`Not a valid token`	Your token may have expired. Generate a new one via the Authorize endpoint
`403`	`Access forbidden`	Your account may not have access to this API. Contact support
`400`	`X-Deepvue-Origin must match ^[a-z0-9][a-z0-9-]{0,31}$`	Use only lowercase letters, digits, and hyphens, up to 32 characters. See Identifying your caller

Was this page helpful?