API Keys

API keys let you script or integrate against the BB API without an interactive session. They’re scoped to a user, carry explicit permissions, and authenticate through the standard Authorization: Bearer header (or Basic auth for Git clients). Once the server accepts a key, the request inherits the key owner’s permissions—letting you call the same certificate and device endpoints that the web console uses.

Important: API keys are bearer secrets. Treat them like passwords—store them securely, rotate them regularly, and delete keys you no longer need.

1. Getting an API key

Most users generate keys in the BB web console. Copy the ak_… token when it is first shown; it will not be displayed again. You can also create keys via the REST API (see Managing keys via API), but for day-to-day usage the console is usually faster.

Make sure the key includes the permissions required by your automation. Typical scopes include:

• certs.read, certs.write — List, issue, renew, or delete certificates.
• devices.read, devices.write — List devices, assign certificates.
• cas.read, cas.write — Manage private/self-signed certificate authorities.

2. Authenticating requests

REST / JSON clients

Send the key as a bearer token. The backend detects tokens that start with ak_ and authenticates them against the API key store.

curl -H "Authorization: Bearer ak_yourtoken" \
  https://cjj365.cc/apiv1/users/42/certificates

No cookies are required—every request is stateless once the key is supplied.

Git (Basic auth) clients

When cloning or pushing over HTTPS, use any username and set the API key as the password. The server inspects the password, recognises the ak_ prefix, and performs API-key authentication.

# Username prompt: automation-bot
# Password prompt: ak_yourtoken
git clone https://cjj365.cc/git/example/private-repo.git

3. Calling other endpoints with the key

Below are common flows that mirror the web console.

List certificates

curl -H "Authorization: Bearer ak_yourtoken" \
  "https://cjj365.cc/apiv1/users/42/certificates?offset=0&limit=20"

Issue a certificate

curl -X POST https://cjj365.cc/apiv1/users/42/certificates \
  -H "Authorization: Bearer ak_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{
        "domain": "example.com",
        "sans": ["www.example.com", "api.example.com"],
        "acme_account_id": 7,
        "dns_provider_id": 3,
        "key_type": "ecdsa",
        "auto_renew": true
      }'

The operation succeeds only if the key has the same certificate permissions the console would require.

Download a certificate bundle

curl -H "Authorization: Bearer ak_yourtoken" \
  https://cjj365.cc/apiv1/users/42/certificates/1001/export \
  -o cert_bundle.json

jq -r '.data.cert' cert_bundle.json > cert.pem
jq -r '.data.privkey' cert_bundle.json | base64 -d > key.pem

Assign a certificate to a device

curl -X POST https://cjj365.cc/apiv1/users/42/devices/88/certificates \
  -H "Authorization: Bearer ak_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{"cert_id": 1001}'

If the device or certificate belongs to another user, the API returns a 403 with API key lacks required permission.

Poll device install updates

curl -H "Authorization: Bearer ak_yourtoken" \
  https://cjj365.cc/apiv1/devices/self/updates

Automation agents can run this periodically (or long-poll) to detect install changes without creating browser sessions.

Managing keys via API (optional)

If you prefer full automation, you can manage keys with REST as well. These routes require an existing session or an API key with apikeys.write scope.

Method	Path	Description
GET	/apiv1/users/:user_id/apikeys	List API keys (supports offset / limit).
GET	/apiv1/users/:user_id/apikeys/:apikey_id	Fetch a single key record (metadata only).
POST	/apiv1/users/:user_id/apikeys	Create a new key and return the one-time plaintext token.
DELETE	/apiv1/users/:user_id/apikeys/:apikey_id	Delete (revoke) an API key.

The POST response includes a token field only once—store it securely before leaving the page or shell. Subsequent requests return metadata but never the plaintext token.

Best practices

• Least privilege: create separate keys per integration with tailored permission sets.
• Short-lived keys: keep lifetimes tight (hours or days) and rotate keys automatically.
• Monitoring: audit usage via server logs and revoke keys you no longer need.
• Fallback to sessions: interactive sessions still work for bootstrapping keys, especially the very first one.

Troubleshooting

Common error codes when using API keys:

Code	Meaning	Fix
4001	Resource not found	Verify the resource belongs to the key’s user.
4003	Forbidden	Key lacks the required permission—adjust scopes or use another key.
401	Unauthorized	Key expired, was deleted, or the token is malformed.
5000	Internal server error	Retry or contact support if persistent.

If authentication fails you’ll receive api key lacks required permissions or invalid token messaging—double-check the token (including the ak_ prefix) and confirm the key is still active.