BlackBeeCloud documentation

Get unstuck and keep shipping.

Learn the safe, repeatable workflow for auditing an authorized website, understanding findings, coordinating fixes, and verifying the result.

Quick start

1. Create an account

Open BlackBeeCloud, enter your name, email, workspace name, and password, then complete email verification. If a code expires, request another instead of repeatedly submitting it.

2. Create a project

Use a recognizable project name and its canonical production HTTPS URL. Track environments intentionally and never include passwords, tokens, or secret query parameters in a URL.

3. Verify ownership when required

Add the provided challenge through your DNS provider or supported HTTP location, then select Verify. DNS propagation may take time. Verification demonstrates technical control at that moment; it does not authorize testing unrelated third-party infrastructure.

Run an audit

Authentication options

• None: public websites and pages.
• Bearer token: authorized applications accepting an Authorization header.
• Basic authentication: protected staging sites using an approved test identity.
• Session cookie: an existing authorized test session, formatted as name=value.

Use a dedicated, minimal-permission test identity. Never use another person’s session, a long-lived administrator cookie, or credentials without written authorization.

Findings, retesting & reports

Findings include severity, category, explanation, evidence, and a recommended next action. Begin with critical and high items, validate the evidence, group related issues, decide ownership, and consider production impact. A single score never replaces engineering judgment.

After a fix is reviewed and deployed, retest it against the earlier audit. Investigate persistent findings and regressions. Authorized users can produce branded reports and revocable share links; anyone who receives a public report link may be able to open it.

Teams and roles

• Owner: full workspace authority, billing, member control, sensitive integrations, agent authorization, and destructive actions.
• Admin: operational management for trusted team leads without ownership-only control.
• Member: routine project, audit, and remediation participation.
• Viewer: read-focused access for stakeholders.

Use least privilege, review membership periodically, and promptly remove access that is no longer needed.

Connect a coding agent

1. As workspace owner, open the project and select Connect agent.
2. Confirm the project and repository context.
3. Copy the generated setup instructions into the coding agent operating in that repository.
4. Complete the owner approval shown in BlackBeeCloud.
5. Store the credential in the OS credential store or encrypted deployment environment.
6. Start the connector and confirm Agent online.
7. Run an audit and explicitly approve tasks for handoff.
8. Review every diff, test, commit, pull request, and deployment.

AI Workspace

The optional AI Workspace uses your own OpenAI or Anthropic API key to interpret selected project context and recent findings. It can explain issues and propose implementation steps; it does not prove a fix or silently change production.

1. Create a provider key and set provider usage limits and billing alerts.
2. Select the provider and a supported model in BlackBeeCloud.
3. Enter the key over HTTPS and test with a low-risk question.
4. Disconnect and rotate the key if exposure is suspected.

Do not put secrets, private keys, personal information, or regulated data in prompts. Verify every command and code suggestion. Provider charges are separate from the BlackBeeCloud subscription.

API, CI/CD & webhooks

Store an API key in the system making the authenticated request. For example, GitHub Actions secrets for an Actions workflow or encrypted Vercel environment variables for a Vercel function. Never expose it through frontend JavaScript or browser-visible variables.

Copy current endpoints and payload examples from the authenticated integration screen. Keys are displayed once: use separate narrowly scoped keys, store them in an encrypted secrets system, rotate them, and revoke unused ones.

Webhook receiver checklist

• Use HTTPS and verify signatures when supported.
• Reject stale timestamps and unexpected event types.
• Respond quickly and process work asynchronously.
• Make handlers idempotent so retries do not duplicate work.
• Log event IDs and outcomes without secrets or full sensitive payloads.

Customer security practices

• Scan only owned or explicitly authorized systems.
• Use dedicated test accounts and short-lived credentials.
• Store integration keys in encrypted server-side secret stores.
• Review all reports and AI or agent output before changes or deployment.
• Require pull-request review and branch protection for production code.
• Rotate credentials after exposure, ownership changes, or staff departures.
• Revoke public report links and delete data when no longer needed.

Troubleshooting

Audit not found

Refresh and confirm the audit belongs to the current workspace. It may have been deleted or you may have switched workspaces.

Protected audit cannot sign in

Confirm HTTPS, the authentication mode, a current test credential, and access to the audited path. Cookies expire; never send one to support.

Domain verification remains pending

Check the exact host and challenge value, remove accidental quotes or spaces, and allow time for DNS propagation.

Agent remains offline

Confirm owner approval, the exact server URL https://cloud.blackbeedev.com, project ID, connector runtime, outbound HTTPS access, heartbeat activity, and credential status.

Verification email does not arrive

Check spam, confirm the address, wait briefly, and request a new code.

When seeking help, include a safe project or request ID, exact time and timezone, action, redacted error, browser, and expected versus actual result. Remove passwords, keys, cookies, authorization headers, and private customer data.