Verify an API key

POST/auth

Sample request

cURL

curl -X POST -H "x-api-key: $ABYSSALE_API_KEY" \
  https://api.abyssale.com/auth
# {"company":"Acme Inc.","version":"v2026-08-21"}

Node.js

import abyssale from '@abyssale/sdk';

const { data, error } = await abyssale.verifyApiKey();

if (error) console.error(error.id, error.message);
else console.log(data);

Python

from abyssale import Abyssale

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

print(result)

Example 200 response

{
  "company": "Acme Inc.",
  "version": "v2026-08-21"
}

Example 401 error response

{
  "message": "Unauthorized: missing or invalid API key.",
  "id": "unauthorized"
}

Check that an API key is usable, and find out which workspace it belongs to.

Behaviour, limits and caveats

This is the endpoint to call when you want to confirm a key works — it runs the whole authentication path and answers 200 only if all of the following hold:

• the key exists,
• it is still active (a revoked key answers 401),
• and, for a workspace key, the plan includes API access (401 api_access_denied otherwise).

The plan check is skipped for a user-scoped key, which therefore answers 200 here whatever the plan. That is not a loophole: a user key is confined to the plugin surface, so a 200 from this endpoint means "this key is live", not "this key can generate". If you need to know whether a key can drive the API, call a real endpoint with it.

Every failure is a 401, whether the key is unknown, revoked, or on a plan without API access. This endpoint does not answer 403.

The response carries the workspace name, so a caller holding several keys can tell which one it has. Integration platforms use it to label a connection.

Do not use GET /ready to test a key. It is a service health check and is exempt from authentication, so it answers 200 regardless of the key you send — including one that has been revoked.

Takes no request body. It is a POST for historical reasons; live integrations depend on the current shape, so it will not be changed.

Response 200

The key is valid and the plan includes API access.

company string

Name of the workspace the key belongs to.

version string

The API version that produced this response, named by release date (vYYYY-MM-DD). Pattern ^v\d{4}-\d{2}-\d{2}$.

More about version

The API version that produced this response, named by release date (vYYYY-MM-DD). Stamped as a top-level field on JSON object bodies, success and error alike, so a client can always tell which contract answered. There is no version-selection parameter — a single version is maintained at a time.

Two kinds of body are not stamped. Array bodies (the listings) carry no envelope. And a body that already has a version key of its own is left alone — which in practice means Banner, whose version is the generated file's integer counter. So GET /banners/{bannerId} and the synchronous generate are the two responses that do not tell you which contract answered.

The value changes when a new version is released. Match the vYYYY-MM-DD shape rather than pinning today's literal, or your client breaks on the next release.

Errors

Every failure uses the shared error envelope — {id, message, errors?}. Branch on id, never on message. See Errors.

Status	When
401	Unauthorized — missing or invalid API key.
429	Too Many Requests.
500	Internal Server Error — an unexpected error occurred on our side.

Related

• Authentication guide