Deep Dive: Retrieving API Credentials

This guide explains how to generate API credentials for your Scorpion App, how to use them correctly, and the differences between Basic and Bearer authentication.

1. Access Your App Settings

Navigate to your app’s settings page:

https://scorpion.caveon.com/apps/<app_id>/settings

You will see the Get API Credentials button near the top of the page.

A screenshot of a computer

AI-generated content may be incorrect.

2. Generate API Credentials

⚠️ Important: API credentials must be generated at the App level, not the project level.

Project-level credentials are not designed for API integrations and will not work for authenticated Scorpion API calls. Always navigate to your App’s Settings page to generate API credentials.

Click Get API Credentials.

You will receive a warning modal:

API Credentials
Getting API Credentials will invalidate all previous credentials. This action is not recoverable. Are you sure you want to continue?

Click Continue ONLY if either: - You are generating credentials for the first time, OR - You are intentionally rotating/refreshing keys.

⚠️ IMPORTANT: Generating new credentials immediately invalidates all previous credentials. Any integrations using old credentials will stop working.

3. Credential Output

After confirming, Scorpion will generate three values:

A white text box

AI-generated content may be incorrect.

3.1 ID

A unique identifier for your App.

3.2 Secret

A secret value paired with your App ID.

3.3 Authorization (Basic Authorization Token)

Basic <Basic Authorization Token>

This is the only value you need for API authentication. You do not need to Base64‑encode anything. Scorpion generates the full Basic token for you.

📝 Note: “Basic” is part of the token and must remain included.

Example header usage:

Authorization: Basic <Basic Authorization Token>

Authorization: Basic <Base64EncodedCreds>

Example cURL usage:

curl --request POST \
--url "https://scorpion.caveon.com/api/exams/<exam_id>/deliveries" \
--header "Authorization: Basic <Base64EncodedCreds>" \
--header "Content-Type: application/json" \
--data '{
    "examinee_info": {
      "First Name": "Amos",
      "Last Name": "Burton",
      "Email": "amos.burton@example.com"
    }
}'

4. Basic Auth vs Bearer Tokens

Scorpion supports authentication using Basic Authorization, which is recommended for most integrations.

4.1 What is Basic Authentication?

Basic authentication encodes your App ID and Secret together into a Base64 string.

Format:

Basic <Base64(AppID:Secret)>

The server validates this pair on every request.

Why Scorpion recommends Basic Auth:

Credentials can be rotated easily.
No need to request short-lived access tokens.
More secure than passing ID + Secret separately.
Works for all Scorpion API endpoints.
Supports least-access design at the app permission level.

4.2 What is a Bearer Token?

Bearer tokens are typically used in OAuth2 workflows and represent a temporary access credential.

A Bearer token looks like:

Authorization: Bearer <tokenValue>

Scorpion does not currently require Bearer tokens for standard API usage.

Bearer tokens are: - Rotated automatically - Time-bound (expire) - Associated with user-granted scopes

Unless your integration is using a custom OAuth flow, you should NOT use Bearer tokens in Scorpion.

5. Best Practices for API Credential Management

✅ Treat the Secret and Basic token like a password.

Anyone with these values can access your Scorpion project at your app’s permission level.

✅ Rotate credentials periodically.

Especially for customer-facing integrations.

❌ Never store credentials in client-side code.

They must live on a server or secure backend only.

❌ Never email plain-text credentials.

Use secure channels such as encrypted vaults.

✅ Use environment variables in your application.

Example: SCORPION_API_KEY, SCORPION_BASIC_TOKEN

6. Summary

After generating API credentials: - Use the provided Basic Authorization token for all authenticated API calls. - Only rotate credentials when necessary. - Keep all credentials secure. - Use Basic Auth (not Bearer) unless implementing a custom OAuth flow.

Related Articles:

App Permissions Deep Dive – https://support.caveon.com/hc/en-us/articles/43517570013844-Deep-Dive-Scorpion-App-Access-Permissions
App Webhooks Deep Dive – https://support.caveon.com/hc/en-us/articles/44671691855380-Deep-Dive-Scorpion-App-Webhooks
App Widgets Deep Dive – https://support.caveon.com/hc/en-us/articles/43517617001620-Deep-Dive-Scorpion-App-Widgets
Creating Deliveries Via API Deep Dive – https://support.caveon.com/hc/en-us/articles/43517770070932-Deep-Dive-Creating-Exam-Deliveries-via-the-Scorpion-API

Related to