Authentication

Accounts

You may have an existing CostQuest Account if you are already a user of an existing CostQuest application or platform.

If you do not already have an account, you may create one by visiting the MyAccount page and, when prompted to sign in, selecting Sign Up to create a new account. The MyAccount page provides a centralized place to view API usage and manage API keys. We highly recommend storing your MyAccount credentials in a secure password manager.

Overview

flowchart LR
  ACC["CostQuest Account (OIDC/OAuth token)"]

  ACC -->|creates/manages| KEY1["API Key A"]
  ACC -->|creates/manages| KEY2["API Key B"]
  ACC -->|creates/manages| KEYN["API Key ..."]
  
  KEY1 -->|used by| END1["User 1"]
  KEY2 -->|used by| END2["Integration 1"]
  KEYN -->|used by| ENDN["Integration/User ..."]

API Keys

• Keys are the preferred mechanism for accessing APIs.
• They are subsets of and in addition to accounts.
• Accounts can be authenticated only using authorization tokens obtained via an OIDC/OAuth flow. An account is required to create a key.
• If a key is used for authentication, it will be used as the context for resource authorization regardless of whether an account authorization token is present.
• Keys cannot manage resources.
• To use a key, it must be included in each request as a header named apikey with the value of the key.
• Keys can be managed on the MyAccount page.
• Keys that remain inactive for extended periods may be revoked for security reasons.
• Rate limits apply across an entire account and all its keys in aggregate.
• Keys can optionally be assigned their own quota. If the number of credits utilized by an key exceeds its assigned quota, the key will be disabled.
• Keys with a quota of 0 will be limited only by the account quota.
• Notifications regarding key usage will be sent at 75% and 100% of the key quota.

Best Practices

Account holders may need to grant API access to others (e.g., teammates, contractors, vendors, or applications) without sharing their own sign-in credentials. This is accomplished by creating separate keys for each person or integration, and managing them centrally.

Principles

• Do not share account credentials. Account authorization tokens (OIDC/OAuth) are tied to the account and can enable broad access. They should not be given to others.
• Use per-user/per-integration keys. Create a dedicated API key for each person, team, environment (dev/test/prod), or system integration so access can be scoped and revoked independently.
• Account holder retains control. Keys are created, configured, rotated, and revoked by the account holder on the MyAccount page.
• Activity is attributable to keys. Usage generated by delegated keys still counts against the account’s quota and rate limits, and the account holder remains responsible for that usage.

Recommended Workflow

1. Create a dedicated key
   • In MyAccount, create a new API key.
   • Name/label the key to identify who/what it is for (e.g., VendorA-prod, DataTeam-dev, CI-pipeline).
2. Scope access appropriately
   • Grant the key access only to the resources it requires (least privilege).
   • Avoid reusing a single key across multiple people or systems.
3. Optionally set a key quota
   • Assign a quota to set a hard cap for that delegated key.
   • Use quota to limit risk for external parties or non-critical integrations.
4. Share and use the key securely
   • Share the key value using a secure method (e.g., a password manager secure link, encrypted secret sharing, or a secrets manager). Do not send keys in plain text.
   • Do not include credentials directly in code. Use secret managers or environment variables.
5. Monitor and maintain
   • Track usage per key via MyAccount or the accountcontrol/getusage api.
   • Rotate keys periodically or when personnel/tools change.
   • Deactivate keys when no longer needed.
   • For a potentially compromised key, deactivate the key, create a replacement key, share it using a secure method, and update dependencies with the new key.