API Keys - QuivaWorks Docs

API keys let you reach QuivaWorks programmatically for automation, integrations and custom applications.

Creating an API Key

Open the API keys tab

Open Settings from your user menu, then the API keys tab

Add a new key

Click Add. A “Create API Key” dialog opens.

Name your key

Enter a descriptive name — “Production integration”, “CI pipeline”, “Monitoring script”

Save the key

The key is displayed once, with Copy and Download Credentials buttons. Take it now.

The key is only shown once. Once you close the dialog it cannot be displayed again. Copy it into a password manager or secret store before you close it.

The API keys tab is not available to users with the client role.

Key Types

Scope

Every key carries a scope. The Settings screen creates user-scoped keys; the account scope is available when a key is created through the API.

User scope

The default. The key is tied to the user who created it and carries that user’s role and permissions.

Account scope

Only root and admin users may create one, and the scope is re-checked whenever the key is used.

An account-scoped key has a far larger blast radius than a user-scoped one. Create one only when a user-scoped key genuinely cannot do the job, and hold it to the same handling standard as the root account’s password.

Restricted keys

Supplying a list of allowed endpoints when the key is created produces a restricted key. Each entry pins the key to a particular HTTP method and path, optionally on a specific gateway. Anything outside that list is refused. Restricted keys carry the msr- prefix instead of ms-, and are the right choice whenever a key only ever needs to make a small, known set of calls — a webhook receiver, a scheduled export, a single integration.

Restricted keys do not come with a downloadable credentials file. Use the key value itself.

Key prefixes

Prefix	Meaning
`ms-`	A standard key
`msr-`	A restricted key, limited to specific endpoints

The prefix uses a hyphen, not an underscore.

Expiry

Keys expire after 90 days by default. When a key is created through the API the lifetime is configurable, and a negative value produces a key that never expires. You get two emails around expiry:

A warning 7 days before the key expires, provided the key’s lifetime was at least 7 days
A notification when it expires — the key is deleted at that point and stops working

A key that never expires never gets rotated by the platform on your behalf. If you create one, own the rotation schedule yourself.

Managing API Keys

Viewing your keys

The API keys tab lists your keys with these columns:

Column	Shows
Name	The name you gave the key
Account	The account the key belongs to
Last 4 Characters	The final four characters, for identifying a key you hold
Created	When the key was issued
Expires	When the key stops working

There is no “last used” column, and QuivaWorks does not currently provide audit logs for API usage. If you need to know when and how a key is being used, log that in the application that holds the key.

Downloading credentials

Download Credentials in the tab’s menu produces a credentials file for a key you already hold — you paste the key value in to retrieve it. It is available for standard keys, not restricted ones.

A downloaded credentials file authenticates as the key. Store it the same way you’d store the key itself, and delete it from your Downloads folder once it’s in your secret store.

Deleting a key

Use Delete Key in the tab’s menu, or open a key from the list and delete it from there.

Deletion takes effect immediately. Anything using that key stops working at once, so deploy a replacement first.

Security Best Practices

Treat API keys like passwords. Never share them or expose them publicly.

Storage and handling

Use environment variables

Do this:

export QUIVA_API_KEY="ms-your-key-here"

Never do this:

// Don't hardcode keys in your source
const apiKey = "ms-abcdef0123456789"; // BAD

Use a secret manager

Store keys in a purpose-built secret store:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager
A team password manager

These give you encrypted storage, access control, and a record of who read what.

Never commit to version control

Add these patterns to your .gitignore:

.env
.env.local
.env.*.local
*.creds

Even a private repository is the wrong place for a key — forks, access changes, CI logs and backups all leak it.

Rotation

Create the replacement

Issue a new key ahead of the old one’s expiry date — the 7-day warning email is a useful trigger

Deploy it

Update environment variables, secret manager entries and CI configuration

Verify

Confirm every integration works on the new key before going further

Delete the old key

Only once nothing is still using it

Organising multiple keys

One key per environment

Separate keys for production, staging, development, CI and each third-party integration. A leak then has a bounded blast radius.

Descriptive names

The name and the last four characters are all you have to identify a key later:

“Production — web app”
“CI — main pipeline”
“Monitoring integration”

If a Key is Compromised

Act immediately if you suspect a key has been exposed.

Delete it

Settings → API keys → Delete Key. This revokes it instantly.

Issue a replacement

Create a new key — and consider making the replacement a restricted key

Update everything using it

Deploy the new key to every affected service

Review your own logs

QuivaWorks has no API audit log, so your application’s logs are the only record of what the key did. Check them for calls you can’t account for.

Work through the wider response

If the exposure may extend beyond the key itself, follow the incident response steps

Common ways keys get exposed:

Committed to a public repository
Written to application logs in plain text
Pasted into a chat or an email
Included in an error message or stack trace
Left in an unencrypted configuration file or a Downloads folder

Using API Keys

Send the key as a bearer token in the Authorization header:

curl -H "Authorization: Bearer $QUIVA_API_KEY" \
     -H "Content-Type: application/json" \
     "$YOUR_ENDPOINT"

HTTP paths are defined per account by your own gateway mappings, so there is no single shared base URL to publish here. Use the endpoint your account exposes.

Node.js
Python
cURL

const apiKey = process.env.QUIVA_API_KEY;

const response = await fetch(process.env.QUIVA_ENDPOINT, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

import os
import requests

api_key = os.environ['QUIVA_API_KEY']

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(os.environ['QUIVA_ENDPOINT'], headers=headers)

curl -H "Authorization: Bearer $QUIVA_API_KEY" \
     -H "Content-Type: application/json" \
     "$QUIVA_ENDPOINT"

Error responses

Errors come back in this shape:

{
  "status_code": 401,
  "body": {
    "error": "..."
  }
}

401 Unauthorized

Common causes:

The key doesn’t exist or was deleted
The key expired and was removed automatically
The key was copied incorrectly — truncated, or with whitespace
The Authorization header isn’t formatted as Bearer <key>

Fix: check the key still appears in Settings → API keys, then reissue it if not.

403 Forbidden

Common causes:

The owning user’s role doesn’t permit the operation
The resource belongs to a different account
The key is restricted and this method or path isn’t in its allowed list

Fix: check the role of the user who owns the key, and — for an msr- key — whether the call is one the key was pinned to.

429 Too Many Requests

A rate-limited response has a plain-text body, not JSON, and carries a Retry-After header telling you how long to wait.Fix: read Retry-After and back off for at least that long. Implement exponential backoff for repeats.

Checklist

Before creating a key

Decide whether user scope is sufficient — it usually is
Decide whether it can be a restricted key pinned to specific endpoints
Identify which user should own it, since the key inherits their permissions
Choose a descriptive name
Have the secret store ready before you click Add

On creation

Copy the key straight into your secret store — it is shown only once
Record where the key will be used
Note the expiry date

In use

Read the key from an environment variable or secret manager, never a literal
Log API errors, but never log the key
Keep separate keys per environment

Ongoing

Review your key list periodically and delete anything unused
Rotate ahead of expiry — the 7-day warning email is your prompt
Re-check any key that never expires

Troubleshooting

Key doesn't work right after creation

Confirm the key was copied whole, with no leading or trailing whitespace
Check the header format: Authorization: Bearer <key>
Confirm the endpoint exists in your account’s gateway mappings
Confirm the owning user’s role permits the operation

Key stopped working suddenly

It may have reached its expiry date and been deleted automatically
Someone may have deleted it — check whether it still appears in the list
The owning user’s role may have changed, or the user may have been suspended or deleted

Calls refused on a restricted key

An msr- key only permits the method and path combinations it was pinned to at creation. There is no way to widen an existing restricted key — issue a new one with the endpoints you need.

Key accidentally exposed

Delete it immediately
Issue a replacement
Update every application using it
Review your own application logs for calls you can’t account for

Next Steps

Authentication

Secure your user account with MFA

Sessions

Manage active logins

Security Overview

Platform and account security

Incident Response

What to do if an account is compromised

​Creating an API Key

​Key Types

​Scope

User scope

Account scope

​Restricted keys

​Key prefixes

​Expiry

​Managing API Keys

​Viewing your keys

​Downloading credentials

​Deleting a key

​Security Best Practices

​Storage and handling

​Rotation

​Organising multiple keys

One key per environment

Descriptive names

​If a Key is Compromised

​Using API Keys

​Error responses

​Checklist

​Before creating a key

​On creation

​In use

​Ongoing

​Troubleshooting

​Next Steps

Authentication

Sessions

Security Overview

Incident Response

Creating an API Key

Key Types

Scope

Restricted keys

Key prefixes

Expiry

Managing API Keys

Viewing your keys

Downloading credentials

Deleting a key

Security Best Practices

Storage and handling

Rotation

Organising multiple keys

If a Key is Compromised

Using API Keys

Error responses

Checklist

Before creating a key

On creation

In use

Ongoing

Troubleshooting

Next Steps