Authentication

Abyssale uses API Key Authentication: your API key is passed along with every API call, allowing Abyssale to identify your company account and access your data.

How to get an API key

Admin role required

Reading the API key requires at least an Admin role on the workspace.

1. Go to app.abyssale.com and log in
2. Click Workspace settings in the left menu

3. Click API Key in the left menu
4. Click the green Create new API key button

Your API key will be available with a small delay of ~30 seconds. Copy it by clicking the copy icon on the right.

All requests must include an x-api-key header with your API Key.

The webhook signing secret is a different credential

Your API key authorises your calls to Abyssale and can spend generation credits. Webhook deliveries are signed with a separate per-workspace signing secret, which proves our delivery to you and grants no access to anything. It is fetched from GET /signing-secret and never sent in a request header — see Signature verification.

How to test your authentication?

Call POST /auth. It takes no request body.

The SDK tabs assume the package is installed — npm install @abyssale/sdk or pip install abyssale.

cURL

curl -X POST -H "x-api-key: {YOUR-API-KEY}" https://api.abyssale.com/auth
# {"company":"Acme Inc."}

Node.js

import abyssale from '@abyssale/sdk';
// Set ABYSSALE_API_KEY env var before running

const { data, error } = await abyssale.verifyApiKey();
if (!error) console.log(data.company); // Acme Inc.

Python

from abyssale import Abyssale
# Set ABYSSALE_API_KEY env var before running

with Abyssale() as client:
    auth = client.verify_api_key()

print(auth.company)  # Acme Inc.

A 200 returns the name of the workspace the key belongs to — useful when you hold several keys and need to know which one you are testing.

The Node.js SDK and the Python SDK read the same key from ABYSSALE_API_KEY and send the header for you.

What a failure means

Anything wrong with the key answers 401. Read the id in the body to tell the cases apart.

id	Meaning	What to do
unauthorized	The key is unknown or no longer active	Check for a typo, or generate a new key
api_access_denied	The key is valid, but your plan does not include API access	Upgrade the plan

Do not use GET /ready to test a key

/ready is a service health check and is exempt from authentication — it answers 200 whatever key you send, including one that has been revoked. It tells you the API is up, not that your key works.