API keys

API keys are created and revoked in the CHCK partner portal, not via the Partner API. Each key authenticates as the CHCK user linked to your partner account.

Create a key

1. Sign in to the partner portal.
2. Open API keys (/dashboard/api-keys).
3. Enter a name (for your own tracking, e.g. Production backend).
4. Click Create key.

One-time display

The full token is shown only once after creation. Copy it into your secret store before dismissing the dialog. CHCK cannot recover a lost token — create a new key instead.

Token format

Part	Description
Prefix	shbx_ (fixed)
Body	48 random bytes, base64url-encoded (~64 characters)
Total length	~70 characters

Example shape (not a real secret):

shbx_xK9mN2pQ7vR4wT1yU8zA3bC6dE0fG5hJ

What we store

Stored in database	Not stored
SHA-256 hex hash of the full token	Plaintext token
First 12 characters (prefix) for display in the key list

Entropy is 384 bits from the random body — suitable for long-lived server credentials.

Use the key

Authorization: Bearer shbx_<paste full token>

The dashboard shows a copy-ready example after creation:

Authorization: Bearer shbx_…

List and revoke

The dashboard lists active keys by name, prefix (shbx_XXXXXXXX…), and last used time.

• Revoke sets revoked_at; revoked keys immediately receive 401 with error: "invalid_credentials".
• Revocation does not delete historical grading data.

Multiple keys

You may create several keys per partner account (e.g. separate staging and production backends). All keys for the same account access the same CHCK user’s data.

Programmatic key management

There is no public API to mint keys. Keys are tied to dashboard sessions and partner accounts created by CHCK administrators.

If you need automation (CI/CD provisioning), contact CHCK about supported processes.

Implementation reference

Key generation lives in shoebox-platform-web (server action createApiKeyAction) and shares token helpers with shoebox-platform-api:

• generateApiToken() — shbx_ + 48-byte secret
• sha256Hex() — storage hash
• parseBearer() — request parsing

See Authentication for request-time validation.